Comments
Comments are as important as the source code itself. The comments should be compact and easy to understand. There are two types of comments, strategic and tactical comments. The first type covers the intention of a function, that is it describes what a function or method exactly does. These comments are written for the user of a library. The second type of comments describe what a single line of code does, these are meant for the maintainer of the source code. You always should write strategic comments, because these enable other developers to use your code. Tactical comments are only useful for complex functions whose code is not self-explanatory. Bear in mind that too many tactical comments can make the whole source less readable.
| Rule 3. Every file that contains source code must be documented with an introductory comment that provides information on the file name and its contents. |
| Rule 4. All files must include copyright information. |
| Rule 5. All comments are to be written in English. |
One might argue that if a piece of software is developed in a country with a different language, one could also use this language for commenting source code. I object to this idea, mainly for two reasons: First it is common to use English names for variables, functions and classes. So it is quite natural also to use English language for the comments, this makes the whole code more consistent and thus readable. The second argument for English comments is that English simply is one of the most important languages for business affairs. It really makes sense to open your product to a much bigger community simply by speaking a widely accepted language. Or would you like to use a product whose documentation is written in a language you cannot understand? Even if you currently do have no intention to make your code available to people outside your team, you can never know the future.
| Recommendation 6. Use a source code documentation system. |
There are many tools that can generate an API documentation out of the source code comments. Many tools require some special hinting keywords in the comments in order to generate a useful text describing the function, but in many cases the comments itself are still easily readable by humans. Using a source code documentation system is especially useful, as it is much easier to keep comments near functions up to date than to synchronise changes in the API to an external documentation.
Kaya Memisoglu 2005-01-06
