There are two reasons to write a comment:

1. to improve the readability or maintainability of the code; or
2. to provide text for a documentation tool.

If you can’t do either of these, don’t write a comment. Experienced programmers prefer to read and understand code without the aid of comments. They know, from bitter experience, that the code is a more reliable guide to what the program actually does.


However, you will sometimes come up with tricky code after thinking deeply about a problem and
rejecting alternative solutions. In this case, it may help the maintenance programmer (who might
be you, six months later) by explaining why you write the code in a particular way.
The only realistic way of keeping documentation consistent with code is to write the documentation
as part of the code and then extract it using a tool such as Doxygen .Note the use of Doxygen markup such
as \b, \param, and \return. If you use a tool such as Doxygen, use it consistently: provide
documentation for all visible entities in a way that will help others to use the library, or whatever it
is, effectively.

Designed By Blogger Templates | Templatelib & Distributed By Blogspot Templates