Over the course of my, so-far brief, career in software development I have seen a plethora of different coding styles fully blanketing the spectrum from awful to outstanding. Software is not a write-only medium and is read (both by humans and machines alike) many more times than it is inked (or typed, punched, plugged, etc). As such, unless participating in some sort of obfuscated code competition, all code should be written with readability in mind. Over the course of the next few days I will attempt to define basic coding styles for C-style languages (like PHP, Java, C#, and JavaScript), SGML style languages (like XHTML, HTML, ColdFusion, and XML), and SQL as well as some best practices.
To begin, I will start with some basic principles that are applicable to the programming field in general.
First and foremost, in order to attain a higher degree of readability the DRY principle should always be kept in mind. Further, code should generally be as verbose as possible. Verbosity allows writing of self documenting code and keeps comments (which aren’t necessarily updated as often as the code is, which is a bad thing indeed) to a minimum. It is very easy to write terse code using quasi-cryptic operators such as ++ or — and short variable names such as r instead of row. However, while this practice could be considered elegant it can often be difficult to read and can be subject to bug introduction during maintenance (or even development).
Update: After some input from co-workers I thought it best to amend the statement discouraging the use of terse operators like ++ and –. While I personally feel it best to not use them, I can also understand that to some, it is much more readable to see i++/i– over i = i + 1 and i = i -1. If you are unfamiliar with all aspects of these operators than you should avoid using them and instead use the more verbose notation. However, if you choose to use these operators, it may be in your best interest to leave a comment or two about what these operators do if your code is to be maintained by persons without in-depth knowledge of them.
For example, consider the following piece of JS that determines if the two given arrays are equivalent:
for (var i = 0, var j = 0; i < a1.length && j < a2.length; i++, j++)
if (a1[i] !== a2[j]) return false;
return a1[i] === a2[j];
}([1,2,3],[1,2])); //false
This code is a bit cryptic to read and is generally poorly written for a number of reasons, some of which won’t be discussed until the JS portion of this series. It would be much easier to read and maintain if it were written as:
var length1 = array1.length,
length2 = array2.length,
i = 0, j = 0;
while (i < length1 && j < length2) {
if (array1[i] !== array2[j]) {
return false;
}
i = i + 1;
j = j + 1;
}
return array1[i] === array2[j];
}
arrayCompare([1, 2, 3], [1, 2]); //false
The code is much more verbose and it is clear what each variable represents. Since there using a for loop here would make the code much more terse using a while loop makes it much more readable. It is also easy to see that both i and j are incremented once through each iteration of the loop and it is clear what the body of the while and if statements are.
All code should adhere to strict indentation and other white-space schemas. Lines of code should also fit in your IDE (or text) editor’s window without the need for scrolling or window resizing. Unfortunately, this is a little bit subjective as not all monitors are created equally and the size of your window may differ from the size of your fellow developers window, or perhaps the size of your window on another machine. Therefore, I recommend adhering to 79 characters max per line. This will almost guarantee the code will display inside of the editor window without wrapping or the need for scrolling or resizing. 79 characters is the default max of dumb terminal windows.
Such a small character limit may seem like a large restriction, but for comparison, my Eclipse IDE with the navigator and outline windows in view leaves only 101 characters for the text editor at a 1600×1200 resolution. It is possible to be very expressive within 79 characters and anything beyond that should go to a new line and be indented appropriately.
I think that’s a good start. More to come later.
Tags: Best Practices, Programming, Style