Document your Code

I was told this week the code doesn’t need documentation because the developers are good at naming things. So I thought it was time to revisit what kind of documentation should be included in code.

Code Comments

There are 2 common objections to code comments

  1. They are not very useful because the code tells us what the program does
  2. They are often wrong because the code changes but not the comments

This is just the talk of lazy “low effort” developers. I think the agile manifesto “working software over comprehensive documentation” has done more harm than good.

Well written comments are invaluable. I’ve never come across an outdated comment that threw me off in a way that I couldn’t just delete it. 🤷‍♂️

Here are some examples of code comments I find useful

1. Adding context that is not in the code

This code was written because a behaviour in macOS.

// On macOS it's common to re-create a window in the app when the
// dock icon is clicked and there are no other windows open.
if (BrowserWindow.getAllWindows().length === 0) createWindow();

2. Adding intention to the code

There are some things that only work in this order.

// This method will be called when Electron has finished
// initialization and is ready to create browser windows.
// Some APIs can only be used after this event occurs.
app.whenReady().then(() => {
  createWindow();
});

3. Rabbit holes you went down and want to warn others of

Warning, here be dragons. 🐉

// THE OBJECT POLYFILL WILL NOT WORK ON THE WEBKIT 1.0.3 PLATFORM
// import "core-js/es/object";

4. Explaining what is going on that the code doesn’t communicate clearly

Why must public url be the same as window location?

if (publicUrl.origin !== window.location.origin) {
  // Our service worker won't work if PUBLIC_URL is on a different origin
  // from what our page is served on. This might happen if a CDN is used to
  // serve assets; see https://github.com/facebook/create-react-app/issues/2374
  return;
}

5. Add a reference to the bug or issue that prompted the change

Go check the bug description to find more information why the code looks like this.

Sentry.init({
  // BUG AB#3133 Decrease sample rate in production
  // Decreasing sample rate to keep costs down.
  tracesSampleRate: 0.1,
});

6. Description of public modules and functions

In order to get nice intellisense when using this module or function from elsewhere in the code.

/**
 * A button that let's you copy the current value to clipboard.
 *
 * @param {object} props
 * @param {string} props.text - The text to display on the button.
 * @param {string} props.value - The value to copy to clipboard.
 * @param {boolean} [props.isDisabled] - Whether the button should be disabled.
 */
function CopyButton({ text, value, isDisabled = false }) {
}

7. Source of Information

Not going to explain all this crap here. Go read up!

/**
 * The source for these abbreviations is here.
 * https://docs.microsoft.com/en-us/azure/cloud-adoption-framework/ready/azure-best-practices/resource-abbreviations
 */
 let abbreviations = ["aks", "appcs", "ase", "plan", "appi", "apim", ....];

8. Source of Copy/Pasted Code

(we all do it sometimes)

// source: https://stackoverflow.com/a/15289883
function dateDiffInDays(a, b) {
  // Discard the time and time-zone information.
  const utc1 = Date.UTC(a.getFullYear(), a.getMonth(), a.getDate());
  const utc2 = Date.UTC(b.getFullYear(), b.getMonth(), b.getDate());

  return Math.floor((utc2 - utc1) / _MS_PER_DAY);
}

9. In order to understand this code you’ll need to know more about this special topic

We are not making up the rules, they are!

// Official DCC Schema documentation
// https://github.com/ehn-dcc-development/ehn-dcc-schema
function parseDccSchema(dcc) {
}

10. What kind of result you can expect from a module or function

/**
 * Calculator screen. It is divided into a left and right part, where the left part 
 * is the input form and the right part presents the result. If the screen width is
 * less than 768px the left part becomes top and the right part becomes the bottom.
 */
function Calculator() {
  /** implementation.. */
}

Summary

Anyone can write code that computers understand. The challenge is writing code that also humans understand.

If you want to know more about how I document code, check out the convention on my wiki.

Project Conventions are Crucial

In my previous blog post I wrote about the importance of having a convention for grouping and naming resources in Azure. In this article I will explain how to setup conventions for your project. Writing a convention is easy. Making sure it is followed is much harder.

Purpose of Conventions

We write conventions for our projects of the following two reasons

  1. If everyone do things their own way we’ll have a mess. Messes are hard to maintain.
  2. Jotting it down saves a lot of time when we introduce new developers to the team.

Don’t write a lot of conventions up front, but also don’t wait until the absence of conventions turn into a mess.

The Art of Writing Conventions

Writing conventions is the easy part. Here is a sample of how I do it.

My convention or naming resources on Azure.

Don’t feel obliged to add all the bells and whistles if you don’t need them. Here is what I do

  • Versioning, makes governance much easier. A simple document version table at the top will do.
  • Each statement is short and precise. Don’t give room for interpretations.
  • I use RFC2119 to make it clear what’s a rule (MUST), an injunction (SHOULD) or a suggestion (MAY).
  • One statement per line makes it easier to skim through.
  • Numbering each statement will make it easier to reference individual statements. Anchor links are nice.
  • Link to external resources for further reading.
  • You don’t need to justify a statement. Leave it for team discussion.

Keeping it Alive

Conventions that aren’t followed are useless.

Include project conventions in your peer review process.

Take 15 minutes each week (after daily on Fridays) with the team to discuss each convention. Update the convention during the meeting. This will make the whole team aware of the convention and the conventions will be kept updated. If you have 26 conventions you will go through them all every 6 months.

I find these sessions very valuable for the team, and if you replace people often in your team they are a necessity.

Moving on From Here

I’ve posted my conventions from Bring Order to your Azure Account publicly with Creative Commons license. Go ahead and steal those conventions for your own project wiki and update them to fit your team.