Self Documenting Code

Like a lot of devs I went through a self documenting code phase. What eventually changed my mind was two times that we decided we needed to document our code.

First I was on a team that added a dev fresh out of college. Our new dev needed a lot of help and the whole team was pitching in to show him the ropes. Handing off code I had written was a breeze. We also handed off code from our manager who had written some of the earliest web code in the company after reading one book and had been riding the wave of demand ever since. That code was rough but we all paid our dues on it. The whole team came together, realized we had a documentation problem and committed to fixing it. Naturally the features and changes kept rolling in and we wrote almost no documentation.

The second was at a startup that added a director of engineering. This director came in and started making big changes. We stopped everything and wrote documentation for a week. This was really offensive to me because I had been writing self documenting code. I put in the time and carefully factored for clarity. I had my thesaurus at the ready constantly looking for just the right name for every concept. I knew where everything was. Writing long-form in a new wiki felt futile. The wiki syntax was weird and unfamiliar. I didn’t know what to write. Everything I wanted to say was obvious or already clearly stated in the code. The wiki sat idle until it was forgotten entirely with maybe five pages worth of documentation.

It took me an embarrassingly long time to really understand what was going wrong. I had heard the phrase self documenting code somewhere and assigned my own meaning to it. Self documenting for me meant that I only had to write code. It was my get out of writing sentences free card. In writing only code with minimal comments, no matter how much effort I put into clarifying, that code only communicated what was being done and never why it needed to be done in the first place.

If code wasn’t clear enough it needed to be rewritten to clarify. This works great when time allows. Changing the code proves you fully understand it and you leave behind better code for the next person. When time doesn’t allow, you revert your changes. Repeat a couple of times and you understand well enough to make really targeted changes, but not those sweeping changes that will help the next person.

This is one way tacit knowledge forms. You’ve done the work to learn something, built up a mental model and left behind nothing to jog your memory. The next person has to build up that mental model same as you did. The two documentation binges I experienced were drastic overcorrections for the problem of tacit knowledge. Deciding to halt all work and write documentation can lead to a week of minimal progress and a sense of guilt. We don’t necessarily want more documentation. We want less tacit knowledge. We want to remove barriers to writing and sharing information.

Iterate!

Documentation doesn’t need to be comprehensive. You can:

• Leave placeholders for things you don’t understand.
• Annotate sections that might need further clarification.
• Add TODOs to indicate areas that need attention.

Documentation doesn’t need to be perfect all the time. You can:

• Speculate, but always make it clear that you’re speculating.
• Embrace the possibility of being wrong, as it can prompt corrections through Cunningham’s Law.

Location Is Everything

Self documenting code worked for me because it was always right there where I was working. The wiki didn’t get updated, it was too far away. Drawing inspiration from manufacturing’s 5S method – which emphasizes the importance of organizing tools and materials for efficiency – we can apply the same principle to documentation. Code comments are great for putting your thoughts near the code without breaking it. Putting a README.md or other markdown files in your code repo puts them in the middle of your development workflow ensures they will be seen. Documentation that is close at hand is more often updated.

Know Your Audience

Better yet, admit that you don’t! Is the next person to read this going have experience with this tech stack? This subject matter? This architectural pattern? Don’t try to predict the future. Learn from the past. Write what you needed ten minutes or two days ago. Copy, paste, or paraphrase that explanation you got from a coworker in a Slack DM.

Use Links

There’s no need to explain how a job queue works. Link out to another project’s documentation. Cite your sources.

A well placed link can save a lot of time searching for terms that have different meanings in different fields, acronyms, or vendors who name their products to guarantee you cannot find them on google. You can finally give yourself permission to close those five tabs.

When a coworker asks a question you can link to the docs you wrote.

Keep in mind that your docs aren’t perfect. This is less “RTFM Noob!” and more “Oh, I wrote something last month, does that help?” Bonus points if this conversation happens in a shared channel that is searchable. Maybe the next person who needs it finds the docs by searching the channel. Each time you share a link you are answering a question, improving the discoverability of the docs, and subtly promoting the idea of writing documentation.

With a little luck, these ideas will prevent documentation from being a surprise writing assignment. With a little more luck coworkers will see the value in your writing and write the documentation you will need in the future.