We Need to Talk about Proper Documentation

Jeff Wax, Developer
#Phase2 | Posted

How often has something like the following scenario happened to you? You’re working to spin up a new application in NodeJS. You know that a few requirements, like server structure, have been done before and are in wide use. Quickly you pull a server module from NPM, enable it and configure as best you can from the included example, but realize that there are a few small changes necessary in order to work with your new app. With a sigh you find the README file in the module’s folder and prepare to dig through a lengthy document for the configuration… only to find that the file consists of npm installmy_node_server , followed by the example you’ve already torn to shreds.

Read Me file image

You dig into the code and find that it’s all scattered everywhere, functions and objects and arrays without a single comment or explanation. Online help is a nightmare, with no website for the author, and no good questions being answered on StackOverflow – just a lot of people who love the module talking about how simple it is and how it’s the best way to approach problems that are very similar to, but not quite, yours.

There’s a phrase to describe people who never experience the problem of low documentation: insanely lucky. Poorly explained or defined code is a routine problem for everyone in the industry, whether they’re working with open- or closed-source, doing the coding or configuration from a UI. I worry that it has become worse as open source has gained more and more traction; with a growing amount of libraries, modules, languages, and platforms, new code is being written every day that can be easily plugged into existing codebases to solve more and more problems. And, every day, that code is being poorly documented, ensuring that future generations of coders will be just as lost and confused as all of the rest of us.

This blog post, and its more technical follow-up, will hopefully convince you that if you aren’t documenting properly, with Readmes, comments, and examples, you should be.

Why Document?

I exaggerate a little, but I can’t help feeling like this is a problem that should have been solved a long time ago. After all, haven’t we all had it drilled into our heads by our coworkers and peers, our teachers and mentors? I had a CS professor in college that would return your code with a 0% if it didn’t have an explanation for every file, logical branch, and parameter. Yet the issue persists: a very rudimentary, rough search of Github shows that 1 in 6 Javascript repos haven’t put anything other than a title into their Readmes.

image of Readme files
This is a file that GitHub requires when you create a repository via their UI. 

All of these are problems that could be solved with better documentation practices: better in-line comments, better organization, and more manageable APIs, to name a few.

“We get it, Jeff,” you might be saying to your screen. “Documentation is important. Everyone knows that.” Except that they don’t. I’m guilty of it myself; just this morning I was unable to recall why I wrote a function the way that I did. “It was important to get working,” I remembered, chin on my fist, “and I thought it was extremely simple. Now it’s breaking the front-end and clearly it isn’t as simple as I thought. But I did it for a reason.”

The Arguments Against

Obviously I’m not the best, or only, example of developers. There are some pretty famous bigwigs who think what I define as “good documentation practices” are actually a sign of bad coding skills. Robert C Martin, aka Uncle Bob, one of the co-authors of Agile and someone who surely knows what he’s talking about, has this to say: “Every time you write a comment, you should grimace and feel the failure of your ability of expression.”

I understand where he’s coming from: good code should be easy to understand on its own. Yet, who knows where your head will be in six months, let alone six years? Who knows who will be looking at your code and need explanation at some later date? You may think your function names and code layout makes this all perfectly clear, but the problem is simple: you’re fallible. Accept that you will fail to express properly from the start. It’s easy to add that extra layer of explanation.

Peter Vogel, an essayist and technologist, once wrote a very controversial article stating that commenting and documenting code was a waste of time and expense because it caused developers to write their code twice: once to document out what the code is doing, and then once to make the code do that thing. “A great comment,” he wrote, “explains what purpose the developer felt that method or class should fulfill. That comment could be extended to include a description of how inputs and outputs of a method are related, and a list of expected side effects. But that’s as far as any comment should go.” His argument is that comments actually describing what the code “does” can be wrong, while code can never actually be wrong: by nature code is what it describes. Plus, if the code changes, the comments need to be updated, as well.

This is actually not a bad argument, but I feel that it completely misses the point of comments and documentation: to do a little bit of extra work now in order to save a lot of extra work later. Vogel is right, of course, that comments can be wrong, just like code itself can be wrong. Again, you are fallible, meaning you can easily make bad comments to go with your bad code. However, there is no “ultimate level of inherent correct-ness:” people, even developers, maybe especially developers, can and will continue to be wrong. But you, as the author of your own code, are the most qualified person to make impeccable, 100% accurate comments describing what your code is doing, as you write it. It can and will save another person.

And in too many cases that other person is going to be yourself.

Where to Start?

“So is that it?” you ask. “Just document things as I write them?” It isn’t the best and final answer to the lack of documentation in the world, but it’s a place to start. Every function, page, and conditional should be commented, along with the usual comments on heavy math or bizarre ternary operations. And we shouldn’t stop at comments — full READMEs are the best thing in the world. Even simple descriptions of how a module or interface can be used save hours of hair-pullingly frustrating time.

photo of Jeff Wax and P2Con

I hope that you’ve read this, nodded or shaken your head a few times, and thought to yourself, “Wow, I really should pay more attention to this stuff.” Because it’s the kind of thing that you only think about when it’s too late. And I can only assume, by the lack of good docs throughout the internet, that it’s still something we don’t all worry about.

Be on the lookout for Part 2 of this post, which will go over good developer documentation and provide several examples of how to write good docs. In the meantime, I hope you take some of these sentiments to heart. A sort of “take-a-penny, leave-a-penny” philosophy could make the world of a difference, changing my story about our poor NodeJS application completely:

You pull a server module from NPM, enable it, and configure as best you can figure, but realize that there are a few small changes necessary in order to work with your new app. With a sigh you find the README file in the module’s folder and open it up. You expect little help, but in a few moments you’ve found the key you need to change in order to make the server work with your unique setup. Just like that, you’re good to go.

Saved by the power of docs.

Jeff Wax

Jeff Wax