651.288.7000 info@intertech.com

Every developer has heard the words “Make sure you document your code.”  What does this mean?  How much documentation is enough?  Most code I have encountered falls onto either end of too much / not enough spectrum of code documentation.  It is very difficult to document the “correct” amount.

To assist resolving this problem, management often sets up rules as to what must be documented.  Rules like “Each method must have javadoc”, or “Every module must have an UML class diagram”.  These rules are an attempt to help, but they often require documentation which is a restating of easily read code, and miss the areas which would help to be documented. So how do we get “good” documentation?  I focus on three guidelines for writing documentation: self documenting code, curated documentation, and context.

Self Documented Code Should be Understandable for the Worst Dev You know

what is self documented code?

Everyone says they write self documenting code, even my Great Aunt Jane writes self documenting code.  Of course it’s self documenting, I wrote it, I understand it, so I’m done.  Then the next person who needs to change the code says “What does this do?  Why does it do it this way?” Well that person just isn’t smart enough to understand this self documenting code.  We need to focus on lowering the bar for understanding.  Remove the “You must be this tall to ride the ride”, and make the code understandable for the worst developer you know.

I do this by writing very clear variable names.  It’s better to have names which you feel are too long, than names which are not 100% clear.  I see the following block of code (or something similar) over and over:

for (int i = 0; i < books.length; i++) {


Everyone knows that “i” is usually the index of an array we are iterating over, so what’s the big deal?  The issue here is when this block of code grows over the course of 10 years, and now this variable “i” is used across a 1000 lines of code.  A better variable name would be bookIndex.

I also make sure to keep the cyclomatic complexity of my code low.  Cyclomatic Complexity is the measure of the number of paths through a section of code.  This number is a great indicator of how tall you must be to ride the ride.  The lower the number the easier maintenance is, and the more likely you won’t be the person required to maintain the code, you can be off writing new features.

I personally use static code analysis to keep track of how well my code is self documenting.  Even when I’m working with a group who doesn’t perform any static code analysis, I install a SonarQube server for myself.  This allows me to focus on solving the problem, and let the tool point out where my code could be better.  Are most static analysis tools overly picky?  Maybe, but if you make the tool happy, then the code is usually very, very clean and easy to read.

For Code Documentation to be Useful, It Must be Curated

curate your documentation

Someone must be responsible for making sure the documentation is up to date, and accurate.  The typical way I see code documentation (outside documenting within the code), is using a tool such as Confluence.  I need to document how these two components interact, I’ll just write a page in Confluence.  Confluence is a great tool, but it frequently turns into a pile of documents which people search through hoping to find what they need.  Then the document is out of date, or inaccurate.  It is difficult to keep documentation curated.

I always place as much documentation as possible in source control, right next to my code.  This makes many people uncomfortable until they try it for a few months.  All documentation generated by developers should live in source control.  I frequently hear “But my manager doesn’t use Git, how will they get the documentation?”  If the audience of the code documentation is outside of the developers, add a build step to publish this documentation somewhere more friendly to outside groups.  When documentation is part of source control, it becomes curated just like the source code.  It is part of code reviews to keep is up to date and accurate.  It is versioned with the source code, no more “Is this document for version X or Y”.  If the document isn’t worth keeping in source control, it probably isn’t worth a developer writing.

How to Find What Code to Read

make sure your documentation has context

Now that you have self documenting code, and your other documentation is curated, what do we document?  Since we already know what the code does (it’s self documenting right?), how do we find what code to read?

We need a roadmap for the code to help find where to add new features, where to fix a bug, or which API to use.  Provide context to the code.  Document what the parts of the system are, where they execute, and why they exist.  This will allow new developers (or you in 2 years) to quickly find the component which needs extension, or modification.

The second type of context falls under the question “This is terrible, why would anyone write this code?”.  Frequently the code that we write lies next to old libraries, inaccurate external data sources, and poorly written old code.  We are forced to write code which doesn’t make any sense without the context of the issue we were working around.  Document these quirks, either right next to the code, or point to an external document within the code.  I always write notes to my future self reminding me of the bump in the road I need to drive around 2 years later.

Your Code Should Now be Documented Well

code documentation makes it easier to fix bugs

Now when I go back to fix bugs in old code, I always have all the code documentation I need.  The documents are sitting in the same repository as the code, no need to worry about who upgraded the wiki 3 years ago and dropped the old data.  The code is simple and easy to read, which I need since the customer called me with their system down at 3:00am on a Saturday (not a time of my peak performance).  I then follow the map laid out in the documentation, work around the strange library quirk, fix the bug and get back to bed.

Code documentation is hard.  It’s easy to write rules about what to document, and check off the box which says that the code is documented.  It’s much harder to provide context to a problem, which is always available and accurate.

Download the full eBook and Infographic for free!