You are currently offline, so some features of this site may not work fully.

Your browser doesn’t support some of the latest CSS features used to build this site.

Read more about my usage of new CSS features.

Document All The Things!*

*Don’t - read on and see first.

I’m big fan of documentation — whether it’s well-detailed README in a public GitHub project, coding standards for a development team or documentation blocks within code — I always find comprehensive notes or instructions invaluable when working on a project, whether legacy or brand new.

I’m going to focus on the last type in this blog - inline code documentation, or Doc Blocks.

Languages you can do it in: Java, PHP, C#, JavaScript, Sass.

JSDoc. SasSDoc.

Who’s this “Todo” guy, and why doesn’t he ever finish his code?

— Callum Ashton

For example, I came back from a holiday to review the front end code that had been written in my absence and the developer had followed my conventions, writing JSDoc comments in the new JavaScript files that had been created:

   * @file grid - uses Masonry Layout NPM package to add functionality to the page grid. Needs shim for IE (even IE 11!).
   * @see {@link}
   * @see {@link}
   * @author N. Redacted <[email protected]>

Now I know clearly what this JavaScript file is trying to achieve, who wrote it so if there are any quirks with it I can contact them quickly, and also links to 3rd-party plugins used so I don’t have to track them down myself.

You can even let people know that there’s something that needs refactoring:

  * @todo Move into utils module

Arguments for:

  • Increases readability of code
  • Lessens the cognitive load of figuring out what code does
  • Can generate documentation in HTML format or reports from doc blocks
  • Can clearly see ownership of code and get contact details

Arguments against:

  • “Code should document itself”
  • Time it takes to write doc block comments
  • Could just use Git logs to see who wrote a piece of code
  • Updating and maintaining comments takes up time
  • People don’t trust comments that are outdated

Further resources: