15.05.2013, 13:02
Beautiful, Readable Code: Version 1.
Audience
It has come to my attention that poor scripting habits lurk left and right in the SA-MP community. This isn't a surprise considering the fact that most scripters are taking their first steps on these forums to produce code which offers immediate gratification. If you have ever found yourself wondering whether or not to indent, how to structure a set of statements, how to use comments effectively, or even looking up a plugin which indents for you automatically, then this tutorial is for you.
Oh, and one more thing! I have gone ahead and underlined key points in each section of the tutorial. Even if for some reason you don't understand any part of a particular explanation, make sure you understand the underlined key point!
Benefits
Proper indentation is the groundwork for writing beautiful, readable code. Although this point may have already been stressed to you at one point or another along your journey, you should be writing your code with the intention of it being readable for someone other than yourself. Even if you never intend to show your code off or introduce someone else to it, writing readable code makes troubleshooting easier and modifications less difficult to implement. Besides, you never know when you may take a break from the project you are working on and come back a few months later. If your code isn't readable, you will find yourself frustrated and unproductive.
Indentation
Indentation is arguably the most prominent factor in writing beautiful, readable code. Do you know how to indent properly? Let's find out.
First and foremost, we need to cover the idea of "nesting." Nesting is the use of those neat braces: { } to nest one statement, argument, or function within another. Let's start out with a basic example of nesting.
For this example, I am using a popular command processor named ZCMD for the purpose of simplicity and application. An example of a nest is creating a command using ZCMD. Notice the comments next to the code.
SINGLE NEST:
pawn Код:
COMMAND:heal(playerid, params[])
{
SetPlayerHealth(playeird, 100);// This function (SetPlayerHealth) is nested inside of the command "heal."
}
MULTIPLE NESTS:
pawn Код:
COMMAND:heal(playerid, params[])
{
if(IsPlayerConnected(playerid)) // Nested within the "heal" command.
{
SetPlayerHealth(playerid, 100); // Nested within the if statement "IsPlayerConnected."
}
}
While you may have noticed in the past that loose indentation (improper indentation) only results in warnings, it is extremely beneficial to exercise good indentation when scripting. When you need to create multiple nests within nests, you'll find it much easier to locate the certain pieces you want to change or modify at a later date if they are indented properly.
White Space
White space is your friend! For some reason an obsession with line count (the amount of lines in a script) has overcome the SA-MP community. Stop making generalizations! Line count has absolutely nothing to do with how well a script has been written or how efficiently it will perform. The only reason line count has received such a negative aura is due to the fact that MOST scripts with large amounts of lines ALSO happen to be very poorly written. It is uncommon to find a large script written well, due to the fact that most large scripts are simply edits of poorly-written older scripts. If you utilize the latest plugins, includes, and stay up to date in your methods, line count is not an issue.
Now that I have flipped your world upside down, let's talk about white space! The ability to separate chunks of code with white space is a very powerful tool for creating excellent readability. Your code does not have to be on top of itself! Make some space, allow some breathing room! A couple of lines of space in between commands, for example, can make scanning through code a much more enjoyable experience. That being said, don't go overboard. You still want to display as much code as possible on the screen at any given time. Find the right balance between white space to create separation and readability and still displaying a good amount of code on the screen.
Comments
Another trend in the SA-MP community is the use of extravagant comments to create separation. While there isn't an issue with this practice, it's also not necessary. The real reason I am mentioning comments is not to encourage you to use them for separation, but to use them for what they are meant for: commenting things! Like I mentioned in the first paragraph, you should be writing your code through the eyes of someone else viewing it. This can be hard to do if you don't adjust your thinking accordingly!
Comments are meant to explain SCRIPT-SPECIFIC content, not general concepts of scripting. I find that some scripters tend to go overboard with their comments and begin to rewrite pawn_lang.pdf in the process. For example, in the if statement below:
BAD COMMENT:
pawn Код:
if(PlayerInfo[playerid][Admin] > 0) // Checks if the player's admin level is greater than zero.
Just remember, you don't have to reinvent the wheel in your comments. Keep them short, simple, to the point, and most importantly only utilize them when necessary. While you may think its better to err on the side of caution, really you are just destroying your productivity.
