How to make your code more readable for your future self and others
We’ve all been there — you’re returning to code you haven’t touched in a couple of weeks and you can’t make heads or tails of it. Everything was perfectly clear when you were writing it, but that clarity tends to evaporate over time.
While you’ll always experience that to some extent, there are several things you can do to help your future self (and your teammates!) read the code you wrote a month ago. Much of this advice comes from Clean Code by Robert Martin. The book is written with code examples in Java, and while I’ve never touched Java before I was amazed at how easy it was to read through his “cleaned” code. Despite not knowing the language’s syntax, I was still able to trace what functions were doing. Much of the advice in the book is for advanced programmers, so I’d like to share some strategies for people just starting out (and experts with bad habits on the basics).
First and foremost, proper indenting. Our eyes and brains do not like when there’s a giant wall of code. The lack of visual differentiation between blocks can make it nearly impossible to find the line you’re looking for. Editing becomes an I-Spy challenge as you trace all of the curly braces and brackets and parentheses just to figure out your scope.
Take a look at these two examples. Which is easier to read? Which would you rather debug?
Indentation makes things much easier to physically read, and helps keep the eye from skipping over important bits of information. Beware, though: there’s also the danger of inconsistent indenting — if you’re going to indent, stick with it throughout the file. Code with mixed indenting can be even more confusing than code with none!
All of that prettifying is useful for making your structure clear, but the code will still look like gibberish if you don’t use good naming practices. A few weeks ago I was doing a code review with a programmer I admire. If it’s easy for him to read, he can give more feedback in less time and with much less frustration. My code, unfortunately, was not easy to read because of poor naming practices. There was some frustration. It ended with a ton of advice on how to name things understandably so that a team member could get in a few seconds what had taken us several minutes to walk through. He gave me some excellent advice: naming things well and having readable code is a huge component of teamwork in the programming world. It’s not enough to have a cooperative attitude — you have to create cooperative code too.
Which of these two is easier for your brain to parse? Which would you rather debug?
As you can see, the second is much easier to read through and trace. Here are some of the naming practices used:
- Names should be actual words. Naming things with single letters or mixed letters/numbers (“a1”, “a2”…) should be avoided, as should most abbreviations.
- Names should be descriptive. If a variable is supposed to be a comment submit button and you have multiple submit buttons in your application, commentSubmitButton is better than button.
- Names should be consistent. Keep an internal logic with your names.
- Names should follow a pattern. Mr. Martin recommends using nouns for variables and verbs for methods. Ex: commentText, deleteComment().
This is a small, “just-the-basics” example of good naming practices. Authors and experts like Robert Martin provide many other naming practices, some of which vary from person to person. Not all of them are applicable all the time. For example, the very first item on the list can be ignored when using “i” or “j” as a counter variable. These two letters (and sometimes “k” as well) are widely recognized variable names for iterative variables due to common convention. Basically, this list should be taken as a set of suggestions rather than a list of edicts.
Another way to keep things easy to read is to put your well-named methods to use and abstract out large blocks of code where possible. Having several functions instead of huge blocks of code (however well named and indented!) makes debugging easier — you can pinpoint the error faster since you can narrow things down by function instead of going line by line. This suggestion is much more subjective than the others in this article, but a good rule of thumb is to consider abstracting code out into a function if you have a chunk more than five or six lines long. This doesn’t necessarily include things like if statements, and you may find that setting your threshold higher or lower works better for you or your project.
Ok, so you’ve indented, you’ve named everything beautifully, and your abstracted functions are a delight to behold. What else is there? One of the most subjective things in code: comments.
I haven’t been able to find a definitive style guide to comments, but the general baseline here is that they should add context to your code. That said, try to use comments sparingly — your code should provide a lot of information on its own! I myself am still learning about when comments are and aren’t needed and what information they should convey.
I can’t guarantee your code won’t still look like some kind of Elvish on occasion, but these strategies will make sure future you and your teammates have an easier time translating.*
If you tried out the advice from this article, please drop me a note and let me know how it went for you!
* I know transliteration would be involved too since Elvish uses a different alphabet; don’t @ me
