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:
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.