This document is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 License.
In Section 2.4.3, we discussed the importance of being able to read documentation about a computer language. In this section, we consider the task of writing documentation for our own code.
As with the layout of code, the purpose of documentation is to communicate. The obvious target of this communication is other people, so that they know what we did. A less obvious, but no less important, target is the code author. It is essential that when we return to a task days, weeks, or even months after we first performed the task, we are able to pick up the task again, and pick it up quickly.
Most of what we will have to say about documentation will apply to writing comments--messages written in plain language, embedded in the code, and which the computer ignores.
Here is how to include a comment within HTML code.
<!-- This is a comment -->
Anything between the opening <!-- and closing -->,
including HTML tags, is
completely ignored by the computer. It is only
there to edify a human reader.
There is an example of the use of a comment in HTML code in Figure 2.10 ( lines 6 and 7).
Having no comments in code is generally a bad idea and it is usually the case that people do not add enough comments to their code. However, it can also be a problem if there are too many comments.2.6Comments should not just be a repetition of the code. Good uses of comments include: providing a conceptual summary of a block of code; explaining a particularly complicated piece of code; and explaining arbitrary constant values (e.g., a number).
Paul Murrell
This document is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 License.