17.05.2013, 16:06
Beautiful, Readable Code II - Indentation Styles
Foreword
The idea for this thread was brought to me by Vince in the previous thread, Beautiful, Readable Code I. If you haven't seen that thread yet, I would recommend you read it first by clicking here. In my previous thread I went through several key characteristics of writing readable code including indentation (in general), white space, and comments. That being said, I neglected to touch on indentation styles. I tried to keep my previous thread as "one size fits all" as possible as to not conflict with the different styles of indentation (although inevitably I did). I am creating this thread to explain (in as much detail as necessary for SA-MP scripting purposes) the different styles of indentation and their benefits. I will only be touching on certain popular styles that lay the groundwork for other styles, so to gain a more complete knowledge of indentation styles you may desire to do some reading on your own.
Oh, and one more thing! In the examples I provide I will be creating a simple command using the most popular command processor, ZCMD. If you aren't familiar with the processor, you can read about it by clicking here. Keep in mind that the example command is simply meant to demonstrate indentation.
Benefits
One common misconception is that the length of a script determines how well that script will perform. This is simply not true. The only reason this generalization exists is because of the poorly-written nature of some of the most popular scripts in the community. Somewhere along the line, members of the SA-MP community began to associate a lot of lines in a script with that script being poorly written. While it is possible that a long script is poorly written, on the other hand a script is not poorly written just because it is long. This is an important distinction to understand.
Because of the obsession with line count in the SA-MP scripting community, the choice of indentation styles has been heavily influenced as of recent. As you will see in the examples below, some styles of indentation will produce more lines than others. Keep in mind that despite what indentation style you choose, your script will perform at EXACTLY the same rate. More lines does NOT mean less performance. Instead of focusing on which indentation style creates the least amount of lines, the sole purpose of indentation is readability. Each indentation style affects readability in one way or another, and I will cover these in detail below. While you are reading, focus on which style suits you best and is most appealing. The only benefit that one indentation style provides over another is readability factor, so the indentation style which you find most readable is the one you should use.
One final benefit to understanding indentation styles is flexibility. Although you may find one style more readable than another, you are not always going to be working with code you have written. If, for example, you begin to edit another person's script, chances are they may be exercising a different indentation style. It is important that you are not only able to interpret the style they are using, but you actually must be able to use it yourself! It is vital that the same style of indentation is used throughout an entire script to ensure continuity. This is simply a matter of standards, and while neglecting it won't produce any errors or affect the script itself, continuity of indentation can make a script more readable should a third party ever need to intervene and read a script edited by more than one person. Be flexible!
Allman Style
I have elected to begin this tutorial with the Allman style of indentation because it seems (to me at least) to be the most prominent in the community. Named after Eric Allman, this style of indentation requires the placing of any brace related to a control statement to be placed on its own line. This includes opening and closing braces. See the example below.
ALLMAN STYLE
pawn Код:
COMMAND:heal(playerid, params[])
{
if(IsPlayerAdmin(playerid))
{
SetPlayerHealth(playerid, 100);
}
else
{
Kick(playerid);
}
}
This style of indentation has more recently come under fire in the SA-MP community because it generates more lines than the styles below. Once again, I would like to reiterate that line count in the case of indentation does not affect performance in the slightest. Your main focus in choosing an indentation style should be readability.
Stroustrup Style
As the second most prominent form of indentation in this community (as I see it), we have the Stroustrup style of indentation. This style is identical to the Allman style, except for the placement of the opening brace on the same line as the initial statement. See the example below.
STROUSTRUP STYLE
pawn Код:
COMMAND:heal(playerid, params[]) {
if(IsPlayerAdmin(playerid)) {
SetPlayerHealth(playerid, 100);
}
else {
Kick(playerid);
}
}
This style, once again, has become more prominent in the SA-MP community with the obsession of line count. While it is perfectly fine to utilize this method of indentation, make sure that you are using it because it is more readable in your eyes, not because you want to save on line count. Once again, line count in terms of indentation has no effect on performance.
K&R Style
Finally we have the K&R style, which is actually the style which the Stroustrup style is derived from. The K&R style is similar to the Stroustrup style in that it places the initial brace on the same line as the initial statement and places the final brace on its own line. The exception comes when else or while are used, where the K&R style places the closing brace on the same line as the else or while keyword. See the example below.
K&R STYLE
pawn Код:
COMMAND:heal(playerid, params[]) {
if(IsPlayerAdmin(playerid)) {
SetPlayerHealth(playerid, 100);
} else {
Kick(playerid);
}
}
Summary
I tried to remain as objective as possible throughout this thread; however, it's probably already clear to you which style of indentation I favor. Try not to let my commentary sway you. If you find K&R to be the most readable and you don't mind knowing that the majority of people on this forum who may be working with your code have no experience with the style, then go for it! To once again reiterate the point of this thread (I know I'm beating a dead horse), readability is the most important factor to consider in choosing an indentation style.
