The Secret to Good Code

Documentation

By Scott Rich

1

Table of Contents

(click on titles to jump to sections)

Introduction………………………………………………..…………………………………………..……..…………2

Self-Documented Code Should Be Understandable For The Worst Dev You Know………3

For Code Documentation to Be Useful, It Must Be Curated…………………………………………5

How To Find What Code To Read..…………………………………...………………………………………..6

Conclusion………………………………………………………………………………………………………………….7

Download the infographic here!

2

Introduction

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.

3

Self-Documented Code Should Be Understandable for the Worst Dev

You Know

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.

4

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.

5

For Code Documentation to Be Useful, It Must Be Curated

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.

6

How to Find What Code to Read

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.

7

Conclusion

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.

That is the end of this Code Documentation Guide. We hope you can utilize this guide for your

own implementation. If you need help with a project, check out Intertech’s Consulting services.

If you want to do more learning from an instructor, find a course in Intertech’s Course Finder!