How much documentation should exist in today’s software source code? At one extreme, there is the architect who believed that one line of comment is too much and that code should be self documenting. This person also used Fortran style variables names (short and with all the vowels missing). I am at the other extreme. I comment my code so with the belief that if I comment it correctly, someone else can maintain it.
What do I believe is the minimum amount of documentation that should exist in the source code? At a minimum, every public method header should be well documented. This documentation should include a list describing each parameter and what is returned. In addition, the documentation should explain what the method is suppose to do, including side-effects. My school of thought is that the public methods in a C++ class (or the equivalent in other object-oriented language) should be treated like a contract. Given a set of input, the following will happen. This does not mean that the internals of the method need to be described; it means that description should inform the caller what to expect when invoking the method. The caller should not have to reverse engineer the code that implements the method.
[powered by WordPress.]
jour·nal n. A personal record of occurrences, experiences, and reflections kept on a regular basis; a diary.
"The objection to fairy stories is that they tell children
there are dragons. But children have always known there are
dragons. Fairy stories tell children that dragons can be
killed."
— G.K. Chesterton
"Zoology, eh? That's a big word, isn't it"
"No, actually it isn't", said Tiffany.
"Patronizing is a big word. Zoology is really quite short."
— Terry Pratchett
from "The Wee Free Men"
35 queries. 1.588 seconds