Oh, the ways to document our code!

Vicky Leong
Jan 24 · 4 min read
Photo by Kyle Glenn on Unsplash

Every developers probably know that they should document their code. We know that we don’t write code just for machines, but for other humans as well, even in a one-man team. Knowing doesn’t equate doing, sadly. In the midst of tight deadlines, excitement of a problem solved, or just pure ignorance, we often forgot to think about others who will read what we wrote.

I learned that there are different ways we developers can document our code. Not all of them are created equal. Some are better suited for certain situations and some for others. Without considering their proper usage, even the noblest intention can backfire.

Here are six ways we can document our code:


Side Note

I’m sure you knew this but, just to be safe, let’s do a quick side bar on what documentation is and why we do it.

Our code is a translation of requirements and ideas in our head into something the machines can understand. Documentation is us noting intents, examples, context, thoughts, history, options, decisions, and frame of reference that went through our head but didn’t make it into the actual code.

The goal of documentation should be to transfer what is in our head into another developers’ head.

With that said, let’s get to our list.


1. Sensible Naming

This should be our primary method of documentation. A good name should be accurate, descriptive, concise, and contains just enough context.

Communicates

  • What a piece of data is (variables, classes).
  • What a set of instruction does (functions).
  • Sometimes, how a function will do its job (e.g. sortAphabetically).

Use it

  • All the time

Tip(s)

  • There is no right template for every situation. Consider sensible naming for every case. x can be a perfectly good variable name when working with alphabets or coordinates. Strive for the right signal-to-noise ratio.

2. Common conventions

Some problems are unique; some problems are not. Use common conventions like design patterns, language idioms, and style guides to help developers to be on the same page.

Communicates

  • What problem was encountered.
  • How the problem is solved.

Use it

  • As often as appropriate

Tips(s)

  • Note to self: Get familiar with the common design patterns and your language-specific idioms.
  • See if you can abstract out a general problem from your specific problem.

3. Unit tests

Good unit tests (only possible with good code) can also save others, and you, a bunch of wasted time of “re-understanding” your code in the future. Treat them as first-class code.

Communicates

  • What the requirements behind a piece of code are.
  • Where a piece of code fails (if it does).
  • How a piece of code should be used.
  • How a piece of code should behave under different scenarios.

Use it

  • As often as appropriate

Tip(s)

  • I like the suggestions presented here on how to write good unit tests.

4. Source code comment

Comments come with maintenance cost. If you’re anything like me, you ignore comments until something goes wrong. As a result, they get outdated really quick.

Communicates

  • Why a piece of code is written against common conventions, official docs, best practices, established/agreed architecture, etc.

Use it

  • Sparingly.
  • Save it for code that would make others think “WTF is it this way??”

Tip(s)

  • See if you can document using suggestion #1 and #2 first.
  • A complex regex would fall under those “WTF is it this way??”
  • If there’s no “because” in the comment, it’s probably not a good case for it.
  • If the code looks normal and common, you probably want suggestion #5.

5. Git commit message

Git never forgets. It’s the perfect place to document historic or temporal context of our code. Do this right and your co-workers won’t have to chase you down to ask for explanation of some code you’ve written two, three months ago.

Communicates

  • What behavior/requirement/feature is changed.
  • Why a piece of code has to change.

Use it

  • All the time.

Tip(s)

  • This is my go-to article for git commit message.
  • Not every commit message has to have a body. Sometimes the what and the why (the where, as bonus) can be written concisely in the tile, e.g. Remove deprecated utility functions in the user domain.
  • It will save more time than it takes.

6. Official documentation

If your code is being used publicly, this is a no-brainer. Who wants to use a library without documentation?

Communicates

  • How your code should be used.
  • What problem is the code solving.
  • Why the solution is implemented a certain way.

Use it

  • As often/much as appropriate.

Tip(s)

  • Don’t assume others know what you know. Spell it out.
  • Keep it updated, please.

There you have it: the different ways to document our code.

I would love to hear what you think about the list. Did you learn anything new? Are there statements that are inaccurate or flat out wrong? Have you found another way of documentation that works for you?

Vicky Leong

Written by

Becoming a better front-end engineer one day at a time.