In Agile, when we say "barely sufficient documentation," we're not referring to user documentation. User documentation has been notoriously bad throughout the entire history of the software industry. As an industry, we must do much better with user documentation than we have in the past, but this post is not about user documentation — it's about internal documentation. It's about documenting the design and the code for other developers so that it will be more understandable and easier to work with later.

There are two important aspects to internal documentation, one of which is often neglected: documentation to express what the code is doing, and documentation to express why the code is doing what it's doing.

In traditional software development, we spend an enormous amount of effort documenting what the code does. We do this with design diagrams, specifications documents, and comments in the code. But this kind of documentation can actually become an impediment to maintainability rather than an aide to it.

The ultimate document that explains exactly what the code is doing is the code itself. Anything else is a distant second and as we write more documents that express what the code does, or pepper our code with comments that express what the code is doing, there is a tendency to make the code itself less expressive. This is a mistake.

The reason we use programming languages rather than hexadecimal machine instructions to make a computer do something is so that the instructions are understandable to us, the people who write and maintain the code. We have a very different set of concerns than the computer does. The computer isn't trying to understand the code we write, it simply executes it. But in order for us to change that code, we must understand it. And so we write our software in an intermediate form that's comprehensible to us and can get compiled down into something the machine can execute.

If you look at the code that's generated from our compilers it's highly efficient. And if highly skilled programmers were willing to sit down for many hours they might be able to write code that's even more efficient. But efficiency is not our only concern. We're also concerned with understandability. And if we have to trade some efficiency for greater understandability then it's often worthwhile to do that.

As we take these ideas to their logical conclusions, we realize that the bulk of programming is all about communication. Our jobs as programmers is to make our code expressive so that it's understandable, not just to us but to others as well. And we make code understandable by using metaphors and analogies as well as good intention revealing names to model the domain we're working in. We should name methods for what they do so the name of the method becomes the most important form of documentation.

In the past, I have been accused by managers of encouraging developers to write uncommented code and while this is true I have a good reason for it. Software developers don't like redundancy and if they know they have to write a comment that says what the code was doing, they'll tend to rely on that comment to communicate the intention of the code rather than the code itself. When this happens the code becomes less expressive and it can be a drudge to read.

Instead of writing a lot of comments in code, we should find ways of communicating that information with the code itself so our code is more expressive and there's less need to comment on what the code is doing. However, using block comments to express why the code is doing what it's doing can often be very helpful and appreciated by the people who maintain the code.