A Plea

Pleeeeaase Explain Your Code

The importance of commenting and documenting your software program

Image for post
Image for post
Photo by Annie Spratt from Unsplash

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.

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.

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.

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.

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.


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.

Written by

Data Analyst. Screenwriter. Project Manager. Now, Resume Coach. A student of life and West Coast Swing. A promoter of self from within. www.sunbreakresumes.com

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store