Optional Extra: Documentation¶
Documentation¶
what kind of comments should you put in source code?
what kind of comment should you not put in source code?
some programmers take extreme views on this!
there seems to be little doubt that good comments are an important part of source code, yet programmers have some common excuses for why they might not write comments at all
the four excuses cited by Ousterhout are:
- “Good code is self-documenting.”
- “I don’t have time to write comments.”
- “Comments get out of date and become misleading.”
- “The comments I have seen are all worthless; why bother?”
Documentation: Is Good Code Self-documenting?¶
partly, yes!
things like good variable names can make code much easier to read
- some programmers like veryLongVariableNames
but code sometimes doesn’t contain all the information you need
sometimes it’s impossible to determine from source code alone what exactly the code is supposed to do
for example, is there a bug in this code?:
void fill(vector<int>& v, int a) {
for(int i = 1; i < v.size()) v[i] = a;
}
without some sort of explanation about the intended purpose of this code, there is no way to know for certain if there is a mistake!
you might assume that i = 1
is a mistake, but that’s just an assumption,
and it might be the case that the first location of the vector is unset for a
reason (e.g. maybe it contains special meta-data)
you may also be able to infer from surrounding code how fill
is used, and
from that what it ought to do
but that could take some time, and seems like a lot of pain for a such a simple function
Documentation: Are Comments Worth the Time?¶
yes: but you might have to think long-term
imagine in 6 months time you have to come back to a piece of code you wrote today
will you remember all the details? if there are no helpful comments, then you need to spend a lot of (probably painful!) time re-learning the details you have forgotten
or suppose you start a new job and inherit 10,000 lines of source code written by another programmer who has left for Hawaii and doesn’t want to spend any more time discussing it
- imagine if these 10,000 lines of code were undocumented
- imagine if these 10,000 lines of code came with useful documentation
skipping comments may lead to short-term gains, but in the long run those missing comments can be the source of tremendous pain for you, and others
Documentation: Do Comments get Outdated and Misleading?¶
yes, this can certainly happen: any time you change commented coded, you probably also need to change the comment
but good, useful comments are valuable, and so are worth updating
with sensible commenting practices, keep comments in sync with code is not a deal-breaker and need not be arduous
- note that some programmers are taught that a large amount of commenting is necessary for every function in a program
- sometimes they are required to write substantial documentation for simple programs that they know they will never look at again
- so I suspect that some programmers who dislike comments may be thinking about these sorts of over-written comments that are not very useful
Documentation: If All the Comments You See are Worthless, Why Bother?¶
most programmers have seen worthless comments like this:
// fills v with a
void fill(vector<int>& v, int a) {
for(int& n : v) n = a;
}
this comment says nothing beyond what code says, so it’s not helpful
another example some programmers like to point out is this:
c++; // add 1 to c
if you know what ++
means, then this comment is useless
however, a beginning programmer just learning to program might not know what
++
means, and so such a comment could be quite useful to them!
consider this line of code from Haskell:
show $ parse s -- Haskell
if you know what $
means, then a comment explaining $
would be helpful
but if you don’t know what $
means, you might be unsure what this
computes!
$
in Haskell is low-precedence function evaluation, and it is used to avoid brackets; it’s equivalent to the expressionshow (parse s)
in most real-world software projects, programmers would probably know the basic operators of the language they are learning
- or they would probably learn them pretty soon
and so an experienced programmer might not write “obvious” comments about single operators
but such comments could be valuable to new programmers still learning the language
Documentation¶
in general, good documentation should
- include important things that are in the mind of the designer that can’t be represented in code
- include important things that are not obvious from the code
- follow a standard and consistent style