Comments

Since the dawn of software-based coding solutions, comments have been the bane of software programmers. There are a number of reasons for this. o­ne, many programmers learn in environments where there is o­nly o­ne programmer. Two, programmers feel akin to artists forced to stop mid-masterpiece in order to provide commentary.

However, those resistant programmers realize how important comments are as soon as their boss requires them to maintain the code of a programmer no longer employed by the company. Comments often provide the key to what is otherwise a cryptic mess. It helps us to follow program flow, and it helps readers to skip the sections that are unimportant to them.

This is the reason that most coding standards include a thorough section o­n what and how to comment. Universities even devote entire classes to the art of source code commenting. Professors often frustrate budding computer scientists with the truism that there is no such thing as too many comments. Anyone who has had to maintain the software of another can attest to this.

The universal rule of thumb is that the programmer should write comments as he or she goes, even if that means scribbling incomplete thoughts and returning to them later. The universal rules of comments are that the programmer must comment every global/public variable and property as well as all major functions.

The comments for variables and properties should include the item’s purpose, terms of valid usage, and any other pertinent details. Universal coding standards call for more in-depth commenting o­n major functions. A major function should include a header and that header should include a description of the function’s promise, contract, and requirement.

Another universal rule for commenting is that programmers should comment any section of non-standard code. In this sense, non-standard indicates uncommon code or usage, innovations, kludges, workarounds, etc. The programmer should write these comments in a standard, easily identifiable way.