Pleeeeaase Explain Your Code

The importance of commenting and documenting your software program

Cindy S. Cheung
May 14 · 5 min read
Photo by Annie Spratt from Unsplash

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 (

So why am I such a proponent of documentation?

The Six Benefits of Documentation

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.

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.

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.

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.

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.

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.


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.

Cindy S. Cheung

Written by

Data Analyst. Screenwriter. Project Manager. A student of life and West Coast Swing. A promoter of self from within.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade