3.1-Comments Controversy

Comments are simply blocks of text that JavaScript ignores. While this may not sound useful, the purpose of a comment is to provide a way for the programmer to leave information about what the script does so that when he or another programmer comes back to the script at a future date they will be able to understand what is going on. Some programmers feel that comments are useless, but I personally think this is largely due to the comments explaining how the program works instead of the more important why the code is written this way, what assumptions is the code making, when is this used, where is more detailed information on the algorithm, and who wrote this mess. There are two types of comments. Single line and multi-line comments.

Single line comments start with a double slash (//). Everything on the line after the slashes is the comment. The double slash can start anywhere on a line and can even be on a line that has other programming statements on it. Just remember that anything on the line after the comment is not going to be seen by the compiler.  Multi-line comments start with a slash immediately followed by an asterisk (/*). The comment ends with an asterisk followed by a slash (*/). Anything between the start of the comment and the end of the comment is part of the comment.

Here is some examples:

// single line comment here

/* A multi-line comment here.

 * Note that the asterisk on this line is not necessary.

 * Asterisks are only included here to make the comment look nice! */

 /* A multi-line comment on a single line is allowed */

x = x /* they can also be in the middle of a line of code */ + 4;

There is another type of comment that you may see that starts with /** and ends with */. This is essentially the same as a multi-line comment but there are documentation utilities that will extract these comments and convert them into some documentation files. Often these comments will contain tags prefixed with @ which indicate to the document generator about what type of information is being presented.

One of the pleasant things about compiled programming languages is that you can have as many comments as you wish and when the program is compiled all the comments will be automatically removed from the resulting file. This is not the case with JavaScript but with a utility called a minifier you can get the same results. The idea here then is you document your code and use meaningfull variable names but when you run it through the minifier you end up without comments and have short meaningless variables so the code will dowload faster.

There are many programmers who do not use comments. The primary reason for not using comments is the amount of time it takes to write comments. If the class is going to be used by other people there really is no reason to not write comments once the code is in a stable state. Things that should especially be noted within comment blocks is any type of restrictions or requirements that a method or method parameters require. To-do and assumptions can also be placed in this comment block.

One interesting argument that I heard for not commenting is that comments can become outdated and therefore be incorrect. What I don't understand, and have yet had explained to me satisfactorily, is how a competent programmer could see a comment that his or her changes is making invalid without him or her altering the comment or making note of the changes. This is a real problem as when there are invalid comments in a project, programmers can be misled. Assuming a piece of code does what the comment says it does is just human nature. When bug-hunting, however, one should be looking at what the code is doing as it is a bug because the code is not working the way it is supposed to be working which means that all code, even well commented sections, should be suspect until proven otherwise.

Sadly, in the real world, unrealistic deadlines make proper documentation of code hard if not impossible to do. If comments are too burdensome to write, then at a minimum you should be attempting to write self-documenting code.  This is code that uses very clear names for functions and variables that makes what the code is doing obvious. The problem here is what is obvious to one person may be a complete mystery to another person. Another problem with self-commenting code is that it is fine for explaining how the code is doing something but does nothing about explaining the who, what, why and when aspects of the code, which is the real reason that comments exist.

Related to the controversy is when should comments be written. My approach is to only write comments while I am coding a section if I am doing pseudo code for the section in which case that pseudo code is written out and then filled in as I write the function. Once I have a section of code working properly I try to go over the code to clean it up where necessary and add comments to explain why the code is the way it is.

My code is not the best example of well-commented code but when I have gone back to some of my older code, I have been shocked by how much just the bare amount of commenting that I put into a project has helped. The key areas missing in my code are assumptions about how methods are going to be used are not listed, allowable ranges are often not listed, and unit types are assumed to be known.  I recommend people who do not document their code look at code they have not had to deal with in a couple of years and see how well they understand it.