A Plea
Pleeeeaase Explain Your Code
The importance of commenting and documenting your software program
I attended a workshop on writing technical documentation the other week. The moment I stepped into the venue, I knew I would be the fish out of water, for 1) the workshop was geared toward software developers and I am not a developer and 2) I am a proponent of documentation. I mean, what do you expect? I am a data analyst who writes screenplays for fun!
Yes, as a numbers person myself, sometimes I would rather build the data model or construct an electrical breadboard than write the manual. So I somewhat understand where the developers are coming from. But there have been countless times when I wish at least some documentation existed.
So while waiting for the workshop to start, I networked with a couple of attendees to find out why documentation leaves such a bad taste in their mouths.
Why All the Hate
There are those who do not value documentation what-so-ever and there are those who create technical novels. You would think that there would be people who fall right in the middle, but apparently, there aren’t.
I don’t blame them for having such adverse views. Technical people usually don’t excel in writing, and dread it. Programmers are notorious for not updating the comments embedded in the code or the documentation that goes with it, letting the explanations become outdated. And most troubling of all, a common assumption made by most coders is that any programmer should be able to read the code and know exactly what it does.
That last point is dangerous.
In fact, I fumed when Tim Cook claims learning programming is more important than learning English (http://fortune.com/2017/10/13/tim-cook-coding-english/).
So why am I such a proponent of documentation?
The Six Benefits of Documentation
1. Documentation quickly reminds the creator of what he did in the past.
Have you ever reviewed a script that you coded months ago and forgot exactly what you did? Did you spend hours trying to figure it out again? I have. If the summaries and comments in the code were diligently and consistently kept, the review time should be significantly reduced.
2. Documentation allows anyone who takes over the code to learn faster.
In the same vein, anyone else who needs to take over the code would spend less time learning the code because documentation eases the learning curve. And the less time someone spends reviewing old code, the more time he can spend being productive in creating the new one.
3. Documentation tracks what has been done to the code (i.e. versioning).
It doesn’t make any sense to me why I would find updated code with outdated comments within the same script.
Each programmer is responsible for updating both the code and comments at the same time.
Each time a section of code is finished and working, the programmer ought to edit the comments and save the script as a new version. So I am NOT saying that the programmer must edit the comments while he is still trying to figure out the code. I am saying that once he is satisfied with his completed code, he should update his comments too. Not later. Immediately.
By updating the code and comments in incremental versions, everyone can keep track of what had already been done before.
4. Documentation helps those not as proficient at coding.
Not everyone is a programmer. Many of us, like yours truly, may have coded before but would not consider ourselves expert programmers. And at some point, one of us will be required to at least study the scripts. Without comments or any project specific documentation, the best resource would be the people who developed the script.
But what if they no longer exist in the office?
We end up resorting to general programming resources, then figure out how to implement the information to the actual project. This can be time-consuming and risks revealing company proprietary information when external people ask for specifics in order to provide a solution.
5. Documentation helps technical people translate the code to business value.
What about the people whose primary interest is the bottom line? Writing summaries for the code allows the programmer to see his work at a higher level. Rather than staying in the comfort of the nitty-gritty, programmers will have the chance to contemplate how his work fits into the bigger picture.
As an engineer and a writer, I want to innovate and speak my mind. But all too often, technical people develop state-of-the-art products that have no value to the company or their customers. Groundbreaking products that do not fulfill a need will be rendered useless.
Summarizing the code into laymen’s terms keeps the programmer from going off course. Explanations to business executives would be easier because the connection between the code and the customer need would be clearer.
6. Documentation keeps a record of lessons learned.
Proper project management includes discussions and documentation of lessons learned. This should not only apply to the team as a whole, but it also applies to individual contributors. In fact, a friend of mine keeps a lessons log for her personal life.
Lessons learned does not only document things that should not be repeated. It also documents the things that CAN — and maybe should — be repeated.
Taking the time to review the document at the beginning of the project could prevent repeating mistakes. I mean, isn’t it less excruciating to review lessons learned than staring at the code to find a bug that could have been prevented?
But don’t wait until the end of the project to record the lessons. It is crucial to take responsibility and record them once they are recognized. Otherwise, they could be long forgotten. So if not immediately, at least by the end of the close of business.
Conclusion
In the end, it all boils down to this: Documentation builds empathy for future efforts. It is selfish and irresponsible to only think in the here-and-now and not consider new members who will take over the work or who need to translate it to the bottom line. By creating concise, meaningful documentation, future team members can be more productive and free to innovate. Be smart about it.
