Why Bother With Comments?
Here are some reasons from the programming experts:
|Steve McConnell, author of Code Complete.|
- "Writing a comment makes you think harder about what your code is
doing." ... "If it's hard to comment, either it's bad code or you don't
understand it well enough. Either way, you need to spend more time on the code, so the
time you spend commenting isn't wasted."
- "Comments can take a lot of time for two common reasons. First the commenting style
might be time-consuming or tedious--a pain in the neck. If it is find a new style. A
commenting style that requires a lot of busy work is a maintenance headache: If the
comments are hard to change, the won't be changed; they'll become inaccurate and
misleading, which is worse thatn having no comments at all."
- "Second, commenting might be difficult because the words to describe what the
program is doing don't come easily. That's usually a sign that you don't really understand
what the program does. The time you spend "commenting" is really time spent
understanding the program better, which is time that needs to be spent regardless of
whether you comment."
|Deborah Kurata, author of Doing Objects in Microsoft Visual
- "All modules (forms, standard modules, and classes) should begin with
a brief comment describing the general purpose of the module and any revisions made to the
"All routines (subroutines, functions, and Property procedures)
should begin with a brief comment describing the functional characteristics of the routine
(what it does). It should also include the parameters passed to or returned from the