Maintaining proper formatting and commenting style in writing code is vitally important to programmers of all aspects. The reason why so much attention is paid to our "style" of coding is the fact that a lot of times other people (or even ourselves) read our code (sometimes staring at the code for hours!). Because there are many paths to achieving a goal in programming, sometimes it may not be obviously apparent how or why a certain coding decision was made. By commenting and formatting our code to make it easier to read, we aid the code reader in understanding our work more easily. It even makes debugging our own code easier due to the fact that it will be easier to spot mistakes in "clean" code (not to mention we would probably understand it better through the process of commenting our work!).
What follows on this page are a few general guidelines on how to format your HTML and Javascript code. All examples will be taken from the code on this demo page. Although code snippets are placed on this page when we reference them, it'd be beneficial to take a look at the general layout of the full demo page source code ;-).
Take a look at the following two code snippets:
// calls the randNum function with the parameter 2
randNum(2); //not useful comment!
// generates a random number that is either 0 or 1
// use this to decide whether to go right or down
randNum(2); //useful comment! =D
The second snippet contains much more useful comments than the first one. The first code snippet is basically an english translation of the code. When looking at the code we already know that a randNum is being called with parameter 2. But far more useful would be a short description of what that function actually does. This is especially useful when we cannot see the function or understand it for some reason, by looking at its function calls we get an idea of what it is being used for.
Consider the following code snippet (not from the demo page):
<table>
<tr>
<td>cell</td>
</tr>
<tr>
<td>cell</td>
</tr>
</table>
Note how we indent as we go down each "level". Since the <tr> tag belongs "under" a <table> tag, we indent it one indentation when compared to the <table> tag. The same applies to <td> and <tr>. Since <td> appears within <tr>s only, we indent that one indentation in when compared to the <tr> tag. Once we're done with that level, we indent back out, take a look at the </tr> tags and the </table> tag. Think of this as a heirarchy of tags, as we go down the heirarchy we indent further to differentiate the tags.
Take a look at how we declared and commented the variables in the demo page:
//Declare variables for use later on
// The i and j variables will be used to iterate through the grid
// while the x and y variables store the white box coordinates (row and column respectively)
var i, j, x=0, y=0;
//prefetch images into variables for later use
var red, white;
red = new Image;
white = new Image;
red.src="RedBox.gif";
white.src="WhiteBox.gif";
If an assignment is pretty short like x=0 and y=0, it's okay to put them on the same line. However, if we have longer assignments such as red.src="RedBox.gif" and white.src="WhiteBox.gif", they wouldn't look as good if they were on the same line. Also, we separated the variable declarations/initializations (along with their comments) into two groups. The rationale behind this was because they're really two different types of variables... While the first group are just simple variables, our second group is composed of slightly more complicated objects that have properties and take several statements to declare and initialize.
//The following nested for loops generate the 7x7 grid of red boxes
// The outer loop will iterate through each of the i rows we want to generate (in this case 7)
for (i=0; i<7; i++) {
//This inner for loop will "fill in" the row we're currently looking at (from outer loop) by writing j number of boxes across
for (j=0; j<7; j++) {
document.write("<img src=RedBox.gif>");
}
//Write a breakline to "separate" one row from another
document.write("<br>");
}
We state the general purpose of the nested for loop we have, then we describe in further specifics in what each loop (next to the loop). It's neater to put the description of the for loop above the for loop in question, as opposed to on the side of the for loop, immediately after the {. Also, note how the for loops are structured. This is a lot like the cascading style of heirarchies of HTML code. Because the inner loop is "inside" the outer loop, we indent the entire inner loop one indentation, and anything inside the inner loop is indented another indentation as well. Basically, anything inside braces { } are usually indented. Look at the positioning of the braces too. The opening brace usually follows the loop declaration by one space, and then the closing declaration is on its own line. This indentation and formatting of for loops makes it much easier to read and comprehend loops (which can sometimes get very involving!).
/**
* The function ani() moves the white box currently in the grid either down or to the right.
* It accomplishes this by first setting the current white box to red.
* The function then chooses randomly to whether move down or move to the right with a conditional that checks if a random number was 0 or 1
* If the random number was 0, then it moves the white box's coordinates down a row. Otherwise, it moves the coordinates over a column.
* With the new coordinates of where the white box is supposed to move to, it sets that box to turn into white.
* Finally, it sets up another call to ani() in 300ms. This means that ani() will continually loop and 'animate' every 300ms.
* (every 300ms a new coordinate is chosen, either right or down, and the white box is moved!)
*/
function ani() {
document.images[7*x+y].src=red.src;
if (randNum(2)==0)
x=(x+1)%7; //the modulus 7 operation allows us to 'wrap' around the grid, so if the whitebox goes beyond grid boundaries it will appear on the other side
else
y=(y+1)%7;
document.images[x*7+y].src=white.src;
setTimeout("ani()",300);
}
Our commenting of the function starts with a short general description of what the function does. Then, if the function is somewhat complicated (like our ani() function), we delve into the specifics of how it works, clarifying any algorithms or operators we might use. If even further specific clarification is required, we can enter comments inside the function itself. Again, notice the spacing and indentation of the function. Everything in the function is indented, showing that they are part of the function. Also, look at the conditional statement and how the statements belonging to the if and else conditionals are indented one indentation as well. Remember that if your statements belonging to the if or else conditionals are more than one line long, braces must be used! The braces should be positioned like the for loop braces.
The above commenting guidelines are not representative of any sort of "standard" of commenting within the entire programming community... Commenting and style of programming is more of a personality thing, the above guidelines are what the author usually adheres to but they definitley aren't any type of strict standard...
Page made by Brian Ngo for CSE/INFO 100.