How to Improve Readability in Your Daily Code
Code readability is always essential for a team of developers, especially when the person who writes the code and the person who maintains the code is not the same person. I keep in mind a few tips for improving code readability which are easy to execute:
Put your long, fatty methods on a diet
Short methods are candy in developers’ eyes, and there are already many people advocating it. Though you don’t have to set a hard limit for your method length, some developers have said no method should be more than 20 lines, and I think that’s a good guideline. A good short method should only contain one simple feature or behavior to make it easy to read and understand. Meanwhile, the satisfied feeling of easily reading and understanding the code encourages people to continue reading your code.
Here is a method that sends a username and user data to the server and parses the response:
Instead of putting everything in one method, you can separate it into smaller methods:
Improve your method names
Short methods are preferred and are like seeing green buds growing, and short methods with an accurate name will make your code readers feel warm breeze on their faces. A correct and accurate method name should summarize exactly what the method does, so there are no surprises inside the method. An accurate name shortens the reading process by giving the reader a correct expectation and helps the reader build the connections between different methods without worrying about missing edge cases or checking conditions. An accurate name spares a reader’s effort of code reading, so he or she can focus on reviewing your code rather than remembering which method does what. If your method is short, a simple method name explaining its purpose should be easy.
Add more comments
When most people think about code readability, adding comments is the first thing that comes to mind. Comments help provide background as well as explain the code and thought process very well.
Though an appropriate amount of commenting is useful, comments can be overused:
- When the comments themselves are neither clear nor complete, they can cause confusion. Every developer has thought, “I don’t know what I meant in that comment I wrote six months ago,” or, “I don’t remember why I wrote that six months ago, and now I have a totally opposite opinion.”
- When things get complicated, some developers write down all the information in a huge comment block. The intention is good, but people more likely prefer asking the coder about 50 lines of code to reading through 50 lines of comments. No one likes to read long comments, and a long comment is useless if people don’t read it. Saving your long explanations in a separate document is much better than sprinkling them in a different code base.
- Developers actively update code and can forget to update the corresponding comments, especially if they are long. It is not uncommon to see code evolve over time while the comments remain stale. It is not only a hassle to have to update others’ comments while working on code, but also it is hard to keep track of the comment changes (no tests can catch those). Outdated comments serve no benefit and only harm the code by causing confusion in the future.
Design more clear structure and feature design
When you find that you need to add a lot of comments here and there, or you already spend a lot of effort on code readability, but your co-workers or team members still have a hard time getting the whole picture, consider this as an indicator that your code structure can be better. Clear structure is a big topic that I won’t cover in this article, though I encourage you to spend some time investigating best approaches. Good structure is not only self-explanatory and hence quite readable, but also critical to bug-free and easily maintained code.
Create a feature design document
If you find that long comments are necessary to explain the new feature or change systematically to other developers, put them in a separate design document about the feature. Separating feature descriptions in docs will clean up the code base and improve the readability. In this way, you will not scare readers away with long files of mixed code and comments.
Make simple pull requests
Pull requests which focus on fixing one issue are more welcomed than the ones with multiple issue fixes and features. It might be easy to update some small issues while you work on a big feature, but it will be harder for the code reviewer to focus on the feature while looking for edge cases in your code. If you do have to change something that is not related to the main purpose of the pull request, create a separate branch with the changes and make it a pull request on top of your branch.
Good to go!
If you are following the above guidelines during your daily coding, you will improve your code’s readability without spending too much effort, and gain more love from your developer co-workers! :)
Wenzhi Lin is a Senior iOS Engineer at Appboy, Inc.
