A Few Comments on Commenting Code – When can they add value

Last week we talked about why commenting code should be avoided. But comments aren’t always bad. So when can they add value?

Documentation

Sometimes it is necessary to document publicly accessibly functions, classes – particularly for APIs or libraries where you don’t want developers integrating with it to have to look at the source for the component.

Standards like Javadoc and JSDoc are good examples of comments that provide value by being maintained with the source but can easily be used to generate external documentation. The tools for generating the documentation can easily be integrated as part of your build pipeline, to ensure publicly accessibly documentation is kept up to date.

Standard documentation also allows IDEs to provide features that greatly improve productivity e.g. IntelliSense.

This applies to data too. If you’re unfamiliar with JSON Schema, take a look. It adds a huge amount of value, particularly in documenting requests and responses for an API – accepted values for a particular field etc. In contrast, the likes of JSON.minify adds no value.

Tutorials/Examples/Lessons

A good example of this is happypoulp/redux-tutorial. Comments here are used as a narrative to help a developer learn how to use Redux, in a repository that is entirely a tutorial.

Unavoidable, Unintuitive Hacks

In the words of Papa Roach: This is my last resort…

Some unclear code is unavoidable or the effort in avoiding dramatically outweighs the hack. In these scenarios comments can be useful as long as they focus on why over how, and reference any live issue or further documentation.

A recent example of this was with mscdex/busboy. As discussed in issues/121 and fixed in pull/122, there was an issue where busboy could not be bundled using webpack. A fix had been implemented, but not released.

After weighing up using another library instead of busboy, using another bundler instead of webpack, or implementing custom code to bundle busboy ourselves, we decided it would be best to simply exclude busboy from being bundled and install it separately.

This workaround involved excluding it in the webpack config and installing the dependency explicitly as part of our build pipeline. In both places, we wrote a brief explanation and referenced the issue:

// Bundle busboy separately until issue using webpack fixed (see: https://github.com/mscdex/busboy/issues/121)

It was then clear that once the fix had been released, this workaround can be removed.

ToDos

I’m still unsure whether ToDos in code are useful or counter-intuitive. Although they’re nice reminders, they can add bias to the code base when used in codebases maintained by more than one person. This potentially blinds other developers to alternative solutions.

If I do chose to use a ToDo comment though, I like to ask myself:

  • Is it a reminder for something I need to do before committing the code? If so, it’s okay, no one else will see it.

  • If I’m not going to resolve it before committing, is this something we agree on as a team, or just a personal suggestion.

A personal suggestion is better managed as a GitHub issue or a simple chat, depending on the team size.

If it’s a team strategy, it’s good to track it as an issue in GitHub or other workflow tool like JIRA. This facilitates further discussion. If you decide to use a ToDo comment here, the reference to the issue can be included to allow other developers to easily contribute to the discussion:

//ToDo: [#192] Break this beast of a file up

I’d be very interested to hear anyone’s thoughts on this in particular.

A little humour…

I wouldn’t want to discourage comments like these.

Ultimately, it’s up to you and those who you collaborate with on the codebase how your source should look. In the words of a GCSE English teacher: when writing, consider who your audience is.

Leave a Reply

Your email address will not be published. Required fields are marked *