How to Document Code: 5 Ways to Help Maintenance Programmers

Imagine you’re a software developer working on a financial application. One day you’re assigned (or, if you’re agile, you pick yourself) to implement changes to the overtime computation logic so your company can sell the application in France. In France, the official work week has 35 hours (lucky them) instead of the 40 hours in the US. Being new to the team, you’re not sure where to begin, so you start searching the codebase for the keyword “overtime.”

Let’s see the search results. No, no, no, maybe, no, no, maybe. Hmmm. OK, looks like it’s in this file, and then in this other file as well. Let’s take a look inside.

I see final static int HOURS = 8. What’s that? Looks like eight hours per day…maybe? Then final static int WEEK_HOURS = 40. Looks like 40 hours per week…maybe? Or maybe it’s in this method called getOvertime? I’m not sure where to find the logic I’m looking for.

This is a typical scenario when the meaning of the code is unclear. And it’s a time suck.

What would help you as a developer when modifying and fixing existing code? It’s easy to complain about code written by someone else, but what about the code you write yourself? What do you include so you can help the maintenance programmers who’ll come after you?

The simple answer is that you have to document your code?so your logic is clear, easy to understand, and easy to change.

This article will explain how to do that. We’ll explore what software maintenance is. Then we’ll talk about how to document our code so we can help the other developers who’ll be fixing and modifying the code we write. And since we often get to fix and modify our own code, this will be an article about how we can help ourselves, too.

What Is Software Maintenance?

Before we dive into code documentation, let’s define our terms.

Wikipedia is a good starting point for definitions. Here’s what they say about software maintenance:

Software maintenance in software engineering is the modification of a software product after delivery to correct faults, to improve performance or other attributes.

So what do maintenance programmers do? Wikipedia’s definition continues:

Software maintenance is a very broad activity that includes error correction, enhancements of capabilities, deletion of obsolete capabilities, and optimization.

OK, so what are maintenance programmers?

They’re programmers who change your code after you’ve written it in order to fix bugs or modify functionality. That means every developer is also a maintenance developer. Because unless you’re a wizard who can magically write perfect code,?you’re a maintenance programmer most of the time, too.

So, how do you help your fellow maintenance developers with the code you write? What do you leave behind, inside your code, to help others?

The only really helpful thing you can do is to document your code so your logic is clear, easy to understand, and easy to change. Now, let’s talk about how to do that.

The Code Documentation Controversy

There are many heated discussions in the software development community, and code documentation is one of the topics. The main argument lies around documenting through the code itself versus adding comments. I’ll explain with a simple example that gets to the heart of the controversy.

Which code is better? This:

final static int WEEKLY_OVERTIME_THRESHOLD = 40; (no comment line)

Or this:

// Threshold for computing weekly overtime
final static int HOURS_WEEK = 40; (containing one comment line)

I admit, this is not only a simple example; it’s also simplistic and a bit silly. But l’m just trying to make a point, so stay with me.

Everyone will agree that the first example is the much better choice, since the constant’s definition has the meaning associated with it, baked inside the constant’s name itself. The second example, while shorter, carries a vague meaning.

Now, if you take this simple example and apply it to naming methods, interfaces, classes, and programming logic itself, you can see that vague meaning can grow very rapidly. And vague meaning is the enemy of every programmer.

Vagueness for software developers means extra time needed to understand the context and meaning of all the symbols used. When you try sorting through pages and pages of code, vague meaning adds up to a lot of time. Having to look back at the definitions of terms is easy enough for one term. But it adds up really quickly and slows down every programmer, no matter how experienced and clever they are.

With this in mind, let me explain the controversy some more. There are essentially two code documentation approaches.

Code vs. Comments

As developers, we all agree we want to write code that carries clear meaning throughout. On the other hand, we don’t want to write code that’s vague and requires lots of searching for meaning. How do programmers achieve this?

Some programmers argue that all your software documentation should be the code itself (like in the first example), and that you shouldn’t write any comments (as in the second example). They argue that having to write comments means your code needs refactoring because it’s not clear. The argument of the first camp goes as far as forbidding comments altogether. On the other hand, there are people who argue that code comments are also useful in specific cases in addition to documenting by the code itself.

I, for one, am in the second camp, which means I try to bring clarity to the code itself. But when the code isn’t sufficient, I add comments as well. My goal is striving for clarity?as much as possible?through whatever means I can achieve it. That means even by adding comments.

OK, enough philosophy. Let’s finally talk about helping maintenance developers through documenting our code. Here are five ways to do that.

1. Choose Clear Variable and Constant Names

Variable names are part of the foundation for any codebase. Even though it seems easy to do, choosing meaningful variable names goes a long way to bringing clarity to your codebase. It’s well worth your effort as a developer to pick meaningful variable names and refactor them as you write the code.

I won’t repeat the argument from above, but a constant called WEEKLY_OVERTIME_THRESHOLD is a much better choice than HOURS_WEEK. Similarly, a variable called fileName is much better than one called name.

The more meaning a variable carries, the more clarity it brings to your code. Does it have to be very long? Not necessarily, but I tend to err on the side of length if with it comes more clarity.

2. Choose Clear Method Names and Parameters

Method names are also part of the foundation for any codebase. Naturally, the way we name our methods also has great impact on code clarity.

Let’s say I want a method for finding the number of overtime hours for a week. Again, this is a very simplistic example (I can hear your scoffing; just bear with me) that I’m just using to illustrate my point.

public double determineOvertime (double hours, String country) {
  final double countryOvertime = getCountryOvertime(country);
  final double weeklyOvertime = hours - weeklyOvertime;
  return weeklyOvertime <= 0 ? 0 : weeklyOvertime;
}

This method isn’t completely terrible, but it’s not very clear. There are questions to be asked when simply reading it. We can improve the clarity by adding meaning to the method definition and parameter names, like this:

public double computeWeeklyOvertimeHours (double totalWeeklyHours, String countryName) {
  final int countryWeeklyOvertimeThreshold = getCountryWeeklyOvertimeThreshold(countryName);
  final double weeklyOvertimeHours = totalWeeklyHours - countryWeeklyOvertimeThreshold;
  return weeklyOvertimeHours <= 0 ? 0 : weeklyOvertimeHours;
}

Just by refactoring a few things, I believe we enhanced clarity. Since we’re talking about weekly overtime hours, I made that clear in the method name itself: computeWeeklyOvertimeHours. That has a lot more meaning, and clarity, than the first method name: determineOvertime.

I also changed the input parameters from the generic hours to the more specific?totalWeeklyHours.?The new name?makes the meaning of the parameter clearer. In addition, I changed the second parameter from country to countryName since that’s what it means.

Finally, inside the method itself, I changed the name of the dependent method from getCountryOvertime to getCountryWeeklyOvertimeThreshold. Again, the new name is clearer, as it adds more meaning. I never shy away from using technical terms like threshold?since my audience of fellow programmers will understand them.

3. Add Clarifying Logic Comments

My second example of method naming doesn’t need any extra comments. It’s already clear enough. You can read it from beginning to end and grasp its meaning and function.

But let’s say you get a new requirement.?Something like “Law 123” in France?let’s keep picking on the French?has changed, and it requires that overtime hours be rounded up. (Again, my implementation is simplistic for illustration’s sake, and it in no way represents a solution for a complex financial system.)

To implement this requirement, you would change your code, perhaps to something like this:

public double computeWeeklyOvertimeHours (double totalWeeklyHours, String countryName) {
  final int countryWeeklyOvertimeThreshold = getCountryWeeklyOvertimeThreshold(countryName);
  double weeklyOvertimeHours = totalWeeklyHours - countryWeeklyOvertimeThreshold;
  // France law 123 requires overtime hours to always round up.
  if (countryName.equals("France")) {
    weeklyOvertimeHours = Math.ceil(weeklyOvertimeHours);
  }
  return weeklyOvertimeHours < 0 ? 0 : weeklyOvertimeHours;
}

You’ll have noticed that I added Math.ceil(), which rounds up our result for France only. This is somewhat clear, but I’d argue that this method would need a simple comment. That’s because the change in the code requires some knowledge from outside the system itself. There’s some meaning, beyond the code, that would make the code clearer. The comment line would be something like this:

// France law 123 requires overtime hours to always round up.

It’s this type of logic that may need extra comments. Business logic and domain decisions often require code comments that will help maintenance developers.

4. Maintain Existing Comments

Now that we have cleaner code and some useful comments, we have to make sure we maintain them. When we’re maintenance developers, we also have to maintain existing comments as code logic changes.

In our French example, if the law changes and they want to round down overtime hours, then the comments need to be changed in addition to changing the code.

// France law 123 requires overtime hours to always round down.
if (countryName.equals("France")) {
  weeklyOvertimeHours = Math.floor(weeklyOvertimeHours);
}

Think about what would happen if you changed the code but didn’t change the comment. You’d end up with something very awkward and unclear like this:

// France law 123 requires overtime hours to always round up.
if (countryName.equals("France")) {
  weeklyOvertimeHours = Math.floor(weeklyOvertimeHours);
}

Having the comments say one thing while the code says something completely different is a lot more confusing than having no comments at all! You clearly see that you have to maintain code comments when you change your code.

Over the years I’ve created a simple mental rule I always use when dealing with code comments: I treat existing comments as regular code. This way, I always update existing comments to reflect changes I make to existing code.

5. Refactor, Refactor, Refactor

Changing the code with maintenance in mind requires you, the developer, to think about clarity?not only for yourself but also for those coming after you. In many ways, writing code is like writing an essay. Your logic needs to flow through the words you use. The words you use in programming need to carry information and logic with them in such a way that a maintenance developer gets the point you’re trying to make.

How do you make sure your code documentation gets your point across? Through code refactoring.

When you think you’re done with your code, read it again from top to bottom. Is the meaning getting lost somewhere? If it is, then refactor your variables, constants, and method names so the meaning carries through to the end. In addition, you may also need to refactor the way your objects interact with each other so your logic makes sense.

You Can Help Everyone

Can code documentation help maintenance developers? Yes, it can! Actually, it’s the?only thing?that can help a developer who comes to an unknown portion of code to fix it or change it. By carefully writing your code and refactoring it, you can maintain clarity and definitely help everyone, including yourself. When you read your own code, is it clear? If not, refactor it and add documentation?code itself and comments. If it’s clear, then you’re done!

Learn how GhostDoc can help to simplify your XML Comments, produce and maintain quality help documentation.

About the author

Vlad Georgescu

Contributing Author

Vlad Georgescu is?senior system architect and full-stack enterprise software developer with almost two decades of experience in the development lifecycle. He also has experience as a SCRUM master, agile coach, and team leader. On the communications front, Vlad is also effective: he?s created online communities and worked on social media marketing strategies.

This author does not have any more posts.