From Scratch Web Games: A Beginners Guide to Game Development using HTML, CSS, and JavaScript

Chapter 4.3: Comment 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 think this is largely due to the comments not being written properly as this is often not taught correctly. Far too often I see professors wanting students to use comments to explain what the code is doing. While this is great for the professor to see if the student really does understand what the code is doing, it is not what a comment is for. The code will explain what it is doing. If you need comments to explain what the code is doing, you should probably be re-writing the code as it is not good. Instead of explaining how the program works you should be using comments to explain why the code is written this way, what assumptions the code making, when is this code used, where is more detailed information on the algorithm, and who wrote this mess. If you are using a code repository then you don’t need the who part, and you really should use repos.

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:

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.

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. As I said above, the purpose of a comment is not to explain what code does but other information about the code. The exception to this would be a comment explaining what a method does and what the parameters are. If you are changing this information, you are breaking any code that uses that method so if that code is not matching what the method does, somebody is messing up big time.

There are cases where 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, which is why comments should be used for explaining things other than what code does. Besides, when bug-hunting 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.

I have no issues with programmers not writing comment as long as they are writing 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 explaining what a method does only after I have a section of code working properly. 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. While this may not get them to start writing comments, it should get them to write better self-commenting code.