Category Archives: Software

The Best Code Documentation ‘Tool’ Ever Made

Code Documentation is dreaded by most programmers, and people even question its value. What good is it to have a separate document that describes what the code does, when you can just look at the code?

Of course, code documentation is about outlining the design decisions and how the implementation fits the problem it tries to solve and not just a one-to-one explanation of the code.

Comments as Code Documentation

A lot of people advocate comments as code documentation, and lots of tools and IDEs like Visual Studio has even adopted a syntax within comments to generate code documentation pages where you can browse a class and it’s properties and methods.

Comments as code documentation has a couple of issues, though. First of all, do you ever read them? And what do you expect people to write? Far too often, the comments of a class is just a default text like this:

/// <summary>
/// Helper for constructing Facebook Graph API queries.
/// </summary>
public static class FacebookQueryHelper
{
}

To me, the above comment is just unnecessary clutter.

Another problem with comments as code documentation is that you often forget to update it when you change the code. Say you have a method that does X, Y and Z and you perfectly described what was going on. What if you change the code dramatically, and forget to change the code documentation in the comments? The value of this documentation is now wrong, and you begin to stop looking at it altogether.

Opening up a code base for the first time, and seeing comments that is out of line with the implementation only degrades your perception of the code base and its quality. Over time, it becomes a parody and there’s even long discussions of the best story within comments.

 The Best Code Documentation ‘Tool’

The best code documentation ‘tool’ is just about as simple as it gets. It doesn’t require any download, install or configuration.

The Best Code Documentation ‘Tool’ is: Private methods. It doesn’t get anymore simple than that.

All it requires is that you change the way you implement code a little. Begin to embrace private methods by splitting out a method into smaller chunks, as soon it gets bigger than e.g. 8 lines. I know you can’t have a fixed length to decide when to split out a method into several private methods, but you can find your own criteria and see how it works.

Of course, you shouldn’t go mad and aim for names that documents themselves, but find your own sweet spot instead.

Take a look at this method:

You really need to examine the method to figure out what is going on. It’s all about the ‘how’, and not about the ‘what’. Then take a look at this modified version:

Now it’s very clear that two steps are taken to first of all get the signed request, and then to use the signed request to set the principal.

Make features obvious — forcing usage is even better

When creating software, make your features obvious.

A long time ago, Facebook introduced friendlists – a feature where you can group friends by any name you want.
Along comes Google+, and have a feature called circles that, unlike Facebook’s lists, are very obvious and an integral part of the design and workflow for when adding friends. All over the press, this is the feature they focus on claiming it has an advantage over Facebook. It seems as if they don’t know about the lists feature of Facebook, which makes it very important to focus on the features you need and make them obvious.
People use what they can see, and what they’re forced to use.
It also makes you think about the countless times, when someone says “I hate the bla bla bla” – and most technical minded people just says, “you can turn it off”. This is a typical response, but the problem might be that the defaults are incorrect.