Script Installer documentation page
Script Installer documentation page (Photo credit: Wikipedia)

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?

gcc unter kde
gcc unter kde (Photo credit: Wikipedia)

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?

English: A bug in mathJax
English: A bug in mathJax (Photo credit: Wikipedia)

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.

English: Program Hello World Česky: Program He...
English: Program Hello World Česky: Program Hello World (Photo credit: Wikipedia)

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.

Embed from Getty Images

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.

English: Diagram of the mechanism of using per...
English: Diagram of the mechanism of using perl modules. Deutsch: Diagramm des Mechanismus der Verwendung von Perl-Modulen (Photo credit: Wikipedia)

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.

Lava lamp flowchart
Lava lamp flowchart (Photo credit: Wikipedia)

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”.

Legacy of the Ancients
Legacy of the Ancients (Photo credit: Wikipedia)

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.

Embed from Getty Images

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.

English: Picture of an ancient pipe documentin...
English: Picture of an ancient pipe documenting the foundation of student fraternity Guestphalia Bonn (Photo credit: Wikipedia)

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.

Screenshot of the open source JAVA game Ninja ...
Screenshot of the open source JAVA game Ninja Quest X (I am one of the programmers) (Photo credit: Wikipedia)

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.

Parse tree of Python code with inset tokenization
Parse tree of Python code with inset tokenization (Photo credit: Wikipedia)

One thought on “Documentation”

  1. Interesting thoughts here!

    I think your right about open source software and that documentation is important for how to use these sort of applications. However I think that is where the documentation should stop. It should be a simple, how to page or if its a larger thing such as a framework then maybe an area of the website etc. that gives the use cases for the app/library etc. and allows users to see how to run/use the app. I think documenting the code itself is a huge waste of a developers time. If code needs comments it is badly written, method names, variable names and class names should all explain how the code works. If there is a little bit of magic code in a method/function and its unclear how it works it should be split as best as possible and given a representative name.

    As well as using good coding conventions, tests should document the code too. If an open source project is not using tests it will quickly find its way into hell, with masses of comments which are useless as you explained or even spaghetti code that never gets touched as its just there because nobody understands it. Tests can show intent for the code and express what the developer was thinking at the time of writing the code, with the extra benefit that if someone writes code which breaks the tests you probably have a bug.

    My two cents. Like your blog though!

Comments are closed.

%d bloggers like this: