Virtually anyone who has ever inherited software code from someone else has run into a weird section of code and thought, “What the **** is this?!” And it takes far too long to get an answer to that exasperated question, because documentation is missing or was written with inadequate context. So in an article for AgileConnection, David Bernstein discusses the importance of including both a what and a why in software documentation.
Why Has This Happened?
No agile team ever wants to get bogged down in documentation, Bernstein included, so he looks for ways to provide a maximum of information with a minimum of comments. In particular, Bernstein tries to include very explicit and descriptive names for all of his objects, so that the “what” of code is always implicit. Doing things this way not only cuts down the need for “what” comments, but it also encourages future inheritors to actually read the code as opposed to just skimming the comments.
In turn, that means that when Bernstein writes comments, they are probably “why” comments: They provide the critical context for why code is designed the way it is. This is valuable for myriad reasons. For instance, in situations where the original developer programs things in a specific way to enable easy future expansion, it is still entirely possible that future inheritors will miss that the program was designed that way and try to customize a more difficult solution instead. In this way, a few good “why” comments can save significant time and money.
But the “why” need not be confined just to comments. It is also a good idea to simply film the team for their thoughts during retrospectives, for instance. People can be asked why they decided to design things the way they did, and those insights will all be captured for future recall.
And incidentally, Bernstein considers unit tests to be the best sort of internal documentation:
When a developer practices test-driven development correctly, it has several advantages when reviewing their code. First of all, I know with absolute certainty that their code works by simply running their tests. I can look at their test coverage and verify that all their code, or at least the majority of their code, is under test. I can look at their tests and see how they intended their methods to be called. I can look at the sequence of tests and see how the developer emerged their system to build the feature. All these things let me get into the developer’s head so that I understand not just what decisions they’ve made, but why they’ve made those decisions.
Unit tests are the perfect expression of all these ideals.
For additional insights, you can view the original article here: https://www.agileconnection.com/article/document-why-well-what-finding-purpose-your-software