Writing Readable Code

With some regularity, I will see programmers reference this Stack Overflow answer as their defense for having no comments in their code.

Comments should be very rare and valuable, almost always expressing the “why” and never the “how” (the exception being when the how is complex and not easily discernible from the code).

Every comment is a hint that you may need to refactor to make the code’s intent clearer. Every comment risks becoming out of date as soon as it’s written.

Of course, the programmers who cite this answer are going to be those who were questioned about their lack of comments in the first place.  And if you’re citing this answer in response to being questioned about your code’s lack of comments, then you’ve completely missed the point of Brad’s answer. Just because, as Brad argues, comments are an indication that your code isn’t very clear, doesn’t mean that a lack of comments are an indication that your code is clear.  Comments can help make code clear.  But what’s better than comments?  Self-documenting code.

Consider the following very simple snippet:

The function name and variable names (or lack thereof) leave us no clue as to what the original intent here actually might be.  In this case, it’s fortunate that the code is so simple, but in other cases with more complex code, a programmer (even the original author) might spend a significant amount of time just trying to figure out what the function is supposed to do.

We want our code to be more readable from a plain-English point of view.  When we spend less time figuring out what a particular chunk of code is supposed to be doing, we can spend more time figuring out if it’s even appropriate to call this function at all, and if so, is the function doing what it’s supposed to?  Is the bug here or elsewhere?  These are all things we can’t determine until we’ve figured out what the code is supposed to do.

With such a simple snippet, a very simple one-line comment can go a long way toward telling any future readers what the intent of this whole function is doing.  Nothing within the function is particularly complicated or hard to follow, so we don’t need to bulk the code down with comments.

With the provided comment, we now know what the original author’s intent was here.  We also know he didn’t test his code at all because this function just returns 1  always, no matter our input.  Clearly wrong.

The comment is helpful, but here, it’s really just one of those signs that our code needs to be refactored to make it more clear.  Sure, when we’re looking at the implementation of the function, we can read in plain English what the function is doing, but how about elsewhere, where we’re actually calling it?  We’re calling a function named s() .  If you’re analyzing code that calls this function, you’re going to have all those questions we talked about previously.  What’s this function?  What’s it supposed to do?  Do we need to do that?  If yes, is this actually functioning correctly?

So, rather than a comment, why don’t we give this function a name that will tell anyone exactly what the function does simply by reading the name of the function?

And while we’re at it, let’s give our variables some more meaningful names, and get rid of an unnecessary variable (which is causing our bug) by using a  for-in  loop (essentially every modern programming language as some form of a  for-in  or  for-each  loop).

Now the comment is unnecessary.  We’ve made our source code more self-documenting.  Whether we’re looking at the internals of the function, or we’re calling it from somewhere completely different, the function, its parameters, and its internal variables are all clearly named.  We have to write less documentation when we make the code itself the documentation.

Your code is not allowed to be comment-free until your code is self-documenting enough that anyone with an understanding of how the language’s syntax works can get the gist of what your code is doing.  Well-written code should read relatively close to plain English.

2 thoughts on “Writing Readable Code

Leave a Reply