Programming Proverbs 20: Provide good documentation

 Well what in the world is good documentation? Now there is a question for the ages. Lots of programmers hate to document their work. I've heard more than a few programmers over the years say things like "you want documentation? Read the code. The code is self explanatory." Ah, yeah, right.

Most will agree to some level of comments - what we generally refer to as internal documentation. If you read some of the comments about comments in my earlier post on that subject you'll find plenty of disagreement about that subject. The question of documentation is a little more complicated than that as soon as you realize that there are several types of people involved. There are other programmers who may have to debug, extend or enhance a program. But there are also various types of users who have to use the program. In some organizations there are also people whose job it is to test the software. All of those groups require different types of documentation and different pieces of information.

The amount of documentation and who creates it often depends on the size of the project and the size of the organization. In large professional organizations the people who create user documentation are often specialized technical writers and not programmers at all. But let us focus here on documentation by and for programmers.

I think that the minimum documentation for a piece of code is the list and description of:

  • inputs - names, types and purposes
  • outputs -  types being the most important piece
  • algorithm descriptions

Generally this can be in a comment block at the top of the method/function/routine but it can be valuable to collect the descriptions from all code blocks into a central document. This information allows a programmer to determine, as long as they assume the code works as advertised, to determine if if meets their needs and how they can use it. If a programmer is going to modify or test that code they have enough information to determine what the code does. Or at least what it is supposed to do. Someone pointed out that comments like but code doesn't. In this case a good set of comments allows one to check the code against the comments to understand where things might have gone wrong.

I like pictures -  call them diagrams if you like. I'm an engineer by way of how I think of myself and that means I'm something of a visual person. That is one of the reasons I like tools like the Class Designer in Visual Studio (not available in the Express Editions unfortunately). Besides letting a programmer create the stubs for methods, properties and the like for a class this tool also allows the programmer to show the relationships between different classes. There are other tools available for showing the relationships between different parts of databases. Either drawn using tools or drawn by hand I think that relationship and other diagrams can be a very useful and important part of project documentation. Visual people will see things much quicker viewing an image than reading code.

Of course keeping the documentation updated is always a problem. That makes tools like the Visual Studio Class Designer more valuable. Just as updates to the Class Designer are reflected in the code generated so are changes made directly to the code available automatically in the Class Designer.

Years ago (many years ago) a professor of mine handed me a large deck of cards for a graphic programming library. He said that this was a great library but that the university had no documentation for it. There were not even many comments. No one could use the library, at least not easily, without some documentation. My job was to create that documentation. It was not an easy task but it sure did convince me of the value of documentation. The old line is that the job is not done until the paperwork is done. For programming documentation is the paperwork.

This is the twentieth of a series of posts based on the book Programming Proverbs by Henry Ledgard. The index for the series is an earlier post and discussion of the list as a whole is taking place in the comments there. Comments on this "proverb" are of course very welcome here.

Comments (2)

  1. Bill Locke says:

    I’ve read several of these posts with interest. I was in this business when most of these ideas were thought of and published. Many of these ideas have been proven ineffective in today’s programming environment.

    We work in a very different environment that 20-30 years ago and it changes much more rapidly than before.

    Particularly if you are working with constrained resources (and who isn’t?), is documentation the most important thing? No. The thing to remember is that your primary goal as a programmer is software, not documentation. Of course we’re talking about documenting the code here, not user documentation.

    The problem with most documentation is that it starts with the best intentions, but usually ends up out of sync with the code and then you have a situation that is worse than not having documentation, is having wrong documentation.

    My axim is write documentation ONLY when it hurts to not have it (actually it’s somebody else’s idea, but I use it).

    I think this stuff is worth talking about, but I would hope people will consider other methodologies than what is forwarded here. As you said, it IS 30 years old.

  2. Dating says:

    Well what in the world is good documentation? Now there is a question for the ages. Lots of programmers hate to document their work. I’ve heard more than a few programmers over the years say things like "you want documentation? Read the code. The

Skip to main content