As a Web developer, I’ve often visited a Web site and wondered how a particular function or visual element was achieved, so I take a quick glance at the page’s source to provide a glimpse into the design. Often this involves scrolling through another developer’s esoteric JavaScript code. While I shouldn’t expect another unknown developer to code so I can understand it; this should be the case when developers work for the same organisation. This issue was raised by a recent client, so the chore of constructing a JavaScript standard was undertaken with the intent of it being followed by the development staff.
What should be standardised?
Tackling such a task begins with the question of what should be standardised. The main goal of the project was to formulate guidelines that make possible the creation of readable code. Another task was to encourage adherence, but as a consultant, this was beyond my border. My first thought on adherence was that the resultant document should be considered guidelines rather than standards, because developers are a fastidious group who like to choose rather than be told.
The following items were pinpointed as general coding guidelines:
- Naming conventions
- Comments
- Grammar
- Parentheses
- Spacing
- Braces
- Documentation
Let’s take a closer look at each item.
Naming conventions
Approaching a system developed by someone else can present many challenges with variable names being at the top of the list. Is it easier to figure out the purpose of a variable named account_balance or ab? Single character variable names may be okay for looping indices but not other variables.
The following JavaScript naming conventions were drafted for the project:
- Function names should begin with a lowercase letter, and the first letter of each subsequent new word should be uppercase with all other letters lowercase.
- Class names should begin with a capital letter, and the first letter of each subsequent new word should be capitalised with all other letters lowercase.
- All variables should be declared in first lines of code. In addition, all variables must be declared in functions to keep them local.
- Variable names should begin with a lowercase letter, and the first letter of each subsequent word should be uppercase with all other letters lowercase.
- Variable names should indicate their data type with a consistent prefix (bln – boolean; flt – floating point; int – integer; obj – object; str – string).
- Variable names should demonstrate their purpose.
Comments
All developers realise that comments make code much easier to debug and read, but inserting them during heads-down development is often seen as extraneous to the task at hand. Properly commenting code as it is developed is imperative to increasing its maintainability. The following commenting guidelines were pinpointed:
- All variables should include a short comment describing their purpose; this utilises the double forward slash (//) comment syntax.
- All classes and functions must contain comment sections that provide a description, example usage, parameters (if any), return value (if any), and edit history.
- Any major sections of code should include extensive comments to parlay its purpose. This guideline is vague, but each developer will be aware of situations where enough complication exists to warrant comments.
Parentheses
I’ve always taken advantage of parentheses to ensure the result is calculated as I expect. Besides, it is easier to insert the appropriate parentheses, than recall the orders of operation. For example: Are the following two calculations equal?
- 2 * 3 + 2 / 2 + 2
- (((2 * 3) + 2)/(2 + 2))
The result of the first equation is 9, where the second yields 2. For this reason, as a guideline, it is suggested that parentheses be zealously used to ensure expected results.
Spacing
The white space within code is an often debated subject among programmers. Some like to place spaces at every available location, but others prefer to compact everything with as little space as possible—consider the following two lines:
for(x=1;x<10;x++){y+=x;alert(x);}
Or:
for ( x=1; x<10; x++ )
{
y += x;
alert( x );
}
As far as readability, the second rendition is more pleasurable to read. The terseness of the first line can be confusing to the eyes. Additionally, it is suggested that one blank line should be placed before and after a function/class declaration to increase readability. Furthermore, ample spacing should be included in the comment sections.
Braces
JavaScript utilises curly braces to denote blocks of code such as functions or for loops. There is often much debate on whether the first brace should be on the same line as the first code segment or on a separate line. The following two lines provide a demonstration:
for ( x=1; x<10; x++ ) {
Or:
for ( x=1; x<10; x++ )
{
In this guide, it was suggested that it should be on its own line to foster readability with the same guide for the ending brace. Additionally, the braces should be lined up with the code—this makes it easier for the eye to match up opening and closing braces.
Documentation
Mentioning documentation to a developer is often analogous to spraying a roach with Raid—it is just painful to watch. While system documentation may not always be necessary, code comments must be used to ensure maximum code readability and maintenance. Also, the placement of developer name and date in the code (when changes are made) leaves a trail for questions to be properly addressed.
Enhance productivity through consistency
The development of development guidelines is an arduous process in which the most difficult task to be accomplished is compliance. After all, what good are guidelines when they are not followed? I did find the process rewarding by having the opportunity to review an abundance of code (not mine) and to discuss such development issues with veteran developers.
How do you feel about development standards? Do you use them within your organisation? Share your comments with us.