The Importance of Readability in Code

Author: 

Readability is not something many people think about as being a top priority when they’re writing code. This is usually the case when people get very focused on making something work and making it work well. Especially for solo projects, people aren’t generally concerned about someone else reading their code, so they just write whatever ends up being convenient. Having worked on many group projects in my time here at RIT, and having worked in a professional game development environment during my co-op last summer, I’ve formulated the opinion that readability is always important in virtually every scenario where you have to write code. In addition, if you have to sacrifice readability to improve performance, it’s often not worth it. In this blog post I’m going to give you a few guidelines / ideas to consider, and hopefully show you that writing nice and readable code will benefit you, as well as the people you’ll work with in the long-run.

Names that are Easy to Understand

How do you usually go about naming your variables, methods, and parameters? Do you ever run into the issue where you can’t remember what a variable holds, or what a method does without back-tracking through stuff that you wrote a week ago and no longer quite understand? It may sound kind of ridiculous, but it happens all of the time. I’ve seen plenty of people write brilliant but confusing code, only to forget how it works or how to use it later on. It’s not that they forgot how to code or forgot how to make something function, they just didn’t focus on the code’s readability, and as a result all of that hard work melted away into an abstract idea that just works, but no one knows why. When you assign names, think about what that piece of code is meant to do and how it would be interpreted by someone who has never seen your code before. Don’t condense, be silly / clever with, or randomly assign names in code. It saves so much time when you can just look at a definition and instantly know what it does. For example, if I showed you this method signature: int m(int a, int b); would you know what it does? Probably not right away. What if I had just written: int multiply(int num1, int num2); to begin with? As a rule of thumb, any random person should be able to instantly understand what your variables hold and what your methods do. They don’t need to understand how the data is stored, or how the method goes from start to finish at a glance, but the intention, meaning, and general usage should be abundantly clear.

Single-Purpose Methods

What’s better, one big magic method that does 15 different things, or 15 separate methods that each complete one basic task? The answer is 15 separate methods, and here’s the reason why. Methods tend to get large and unwieldy when you give them multiple things to do. They’re harder to understand, and typically only serve one use case (or in some situations, a lot of specific use cases). You also quite frequently end up writing repetitive code because you need a portion of your giant method somewhere else, so you just copy and paste that part of the method into another block of code. I’m not saying that you shouldn’t have big important functions like “Update” which might handle lots of updating operations, instead I’m saying that “Update” itself shouldn’t hold all of the code for updating every single thing, it should make calls to other functions like “UpdateCharacters” and “UpdatePosition” which would complete smaller, more single-purpose tasks. Writing single-purpose methods will really improve the clarity of your code.

Avoiding Unnecessary Complexity

There will definitely be times while programming when you’ll try to improve the performance of a block of code, only to throw its readability out to the wolves. For example, let’s say you have two lists of equal size, and need to perform an operation on each item in those lists, but a different operation depending on the list. So every item in list A needs to have a number added to it, and you need to calculate the sum of all of the numbers in list B. A clever solution may involve doing everything inside of a single loop (because the lists are equal in size), but you may find that although your solution is clever and efficient, it is near impossible to understand why it was written that way, without understanding the specific context of the problem. Also, what if the problem changes and now the two lists aren’t equally sized, will that clever solution hold up? I’m here to tell you: it’s okay to be less efficient for the sake of readability. Unless you REALLY need to shave off some CPU cycles to get your program to run, always opt to make your code clear and concise. If you do need to increase your program’s performance, there is most likely a better solution that won’t compromise readability, so it’s always better to take your time and implement a clear solution.

Comments or No Comments?

Definitely comment your code, but not too much. Comments can provide nice explanations for abstract / confusing code, but they can also get in the way if you have too many cluttering up your screen. Ideally, your code should be able to speak for itself and should be easily understandable with just a few comments.