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 expression show (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