Documentation

Documentation. The “D word” to programmers. In an ideal world programs would document themselves, but this is not an ideal world, though some programmers have attempted to write programs to automatically document program for them. I wonder what the documentation is like for such programs?

To be sure if you write a program for yourself and expect that no one else will ever look at it, then documentation, if any, is up to you. I find myself leaving little notes in my code to remind my future self why I coded something in a particular way.

Such informal documentation can be amusing and maybe frustrating at times. When reading someone else’s informal documentation such as “I’m not sure how this works” or “I don’t remember why I did this but it is necessary”. More frequently there will be comments like “Finish this bit later” or the even more cryptic “Fix this bit later”. Why? What is wrong with it? Who knows?

The problem with such informal in code documentation is that you have to think what the person reading the code will want to know at this stage. Add to this the fact that when adding the comments the programmer is probably focussing on what he/she will be coding next, the comments are likely to be terse.

Add to this the fact that code may be changed but the comments often are note. The comment says “increment month number” while the code actually decrements it. Duh! A variable called “end_of_month” is inexplicably used as an index to an array or something.

Anyone who has ever done any programming to a level deeper than the usual beginner’s “Hello World!” program will know that each and every programmer has tricks which they use when coding, and that such tricks get passed from programmer to programmer with the result that a newcomer looking at code may be bamboozled by it. The comments in the code won’t help much.

Of course such programming tricks may be specific to the programming language used. While the same task may be achieved by similar means at a high level, the lower level of code will be significantly different. While that may seem to impose another barrier to understanding, I’ve found that it is usually reasonably easy to work out what is going on in a program, even if you don’t “speak” that particular language, and the comments may even help!

While internal documentation is hit and miss, external documentation is often even more problematic. If the programmer is forced to write documents about his programs, you will probably find that the external documentation is incomplete, inaccurate or so terse it is of little help in understanding the program.

In my experience each programmer will document his/her programs differently. Programmers like to program so will spend the least possible amount of time on documentation. He/she will only include what he/she thinks is important, and of course, the programmer is employed to program, so he/she might get dragged away to write some code and conveniently forgets to return to the documentation.

If the programmer is at all interested in the documentation, and some are, he/she will no doubt organise it as he/she thinks fit. Using a template or model might help in this respect, but the programmer may add too much detail to the documentation – a flowchart may spread to several pages or more, and such flowcharts be confusing and the source of much frustrated page turning.

Of course there are standards for documentation, but perhaps the best documentation of a program would be to specify the inputs and specify the outputs and then a description of how the one becomes the other at a high level. As I mentioned above a programmer will probably give too much detail of how inputs become outputs.

Documentation tends to “decay” over time, as changes are made to the program and rarely is the documentation revisited, so the users of the program may need to fill in the gaps – “Oh yes, the documentation says that need to provide the data in that format, but in fact that was changed two years ago, and we now need the data in this format”.

The problem is worse if the programmer has moved on and gone to work elsewhere. Programmers tend to focus on the job in hand, to write the program to do the job required and then move on to the next programming task, so such code comments as there are will be written at the time that the programmer is writing them. Such comments are likely notes to the programmer him/herself about the issues at the time that the program is being written.

So you get comments like “Create the app object” when the programmer wants a way to collect the relevant information about the data he/she is processing. Very often that is all that one gets from the programmer! No indication about why the object is needed or what it comprises. The programmer knows, but he/she doesn’t feel the need to share the information, because he/she doesn’t think about the next person to pick up the code.

I don’t want to give the impression that I think that documentation is a bad thing. I’m just pondering the topic and giving a few ideas on why documentation, as a rule, sucks. As you can imagine, this was sparked by some bad/missing documentation that I was looking for.

Open source software is particularly bad at this as the programmer has an urge to get his program out there and no equal urge to document it. After all, a user can look at the code, can’t he/she? Of he/she could look at the code, but it is tricky to do so for large programs which will probably be split into dozens of smaller ones, and the user has to be at least a passable programmer him/herself to make sense of it. Few users are.

So I go looking for documentation for version 3.2 of something and find only incomplete documentation for version 2.7 of it.  I also know that big changes occurred in the move from the second version of the program to the third undocumented version. Ah well, there’s always the forums. Hopefully there will be others who have gone through the pain of migration from the second version to the third version and who can fill in the gaps in documentation too.