In my last post, I discussed barely sufficient documentation and I said that the best place to express what the code is doing is in the code itself. But there is another form of documentation that we often overlook. It’s actually the most important kind of documentation yet we rarely devote even a sentence to it. The documentation I mean is not about what the code is doing but why we’re doing it in the first place.
Code can express what it does but it’s much harder for code to express why it’s doing that thing. The context for software is often outside of the software itself. The way most teams choose to address this is to completely ignore it, but understanding why we’re making certain decisions or implementing a design in a certain way can be very important in order to gain an understanding of how to extend that design correctly in the future.
When I ask developers why they made a particular design choice they always have a reason. We make decisions based upon the knowledge we have at the time, but very often the reasoning behind our decisions isn’t documented, so it’s lost to future developers who might have to maintain that code.
I strongly believe that although code should express what it’s doing, we still need external documents to describe why the code is doing what it’s doing. Understanding the reasoning behind a design can help us a lot when we go to extend or modify that design.
I distinguish between what I call “what” comments and “why” comments. The what comment describes what the code is doing. When I feel the need to write a what comment, I often step back and ask myself if there are ways to express what the code is doing more clearly in the code itself. Often this leads me to rewrite some of the code so it’s more expressive.
Comments that express why a design is the way it is are entirely valid. We might say that we’re conforming to a federal regulation or that the object we’re using is a collaborator in a specific design pattern. These kinds of comments can be very helpful to readers in the future.
Vision documents and other artifacts can also be helpful in expressing why the code is doing what it’s doing. By understanding that rationale, we’re often better equipped to work with the code in the future. I’ve worked on hundreds of projects in my career and rarely have I ever seen any documentation on why decisions were made, even though many of the developers I talk to agree that this kind of information would be very valuable.
So why don’t we create this kind of documentation? The answer is typically that we haven’t been asked to. If our Product Owner isn’t asking for it, we don’t do it.
An organization has to be aware that these kinds of activities can be valuable to those who will be maintaining the code in the future. Unlike what documentation that often feels like busy work, documenting why we decided to do things the way we did can be a lot of fun. It gives developers a chance to express their reasoning behind their choices and we all love doing that.
So the next time you come up with a design choice, ask yourself why you made that decision then write down the answer. It could be very helpful for another developer in the future.
{1 Comments }
Previous Post: « Barely Sufficient Documentation
Next Post: Keep Defects from Escaping »
See also this article from the latest Thoughtworks technology radar: https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records