What is code readability?

When we write new code we're still fresh on the context, what everything means and how it all ties together. Readability makes sure it stays that way. It is also a great way to help others understand your code, which is quite important when you are trying to collaborate in the same codebase. Don't forget: we tend to read more code than we actually write!

The perfect path to readability

There is no single way to make your code more readable. Plus: different people, teams and companies will have different needs in writing readable code. For example: in my first job my team had a strong "no comments" culture. We tried making variable names speak for themselves and felt like comments were a sign that code was too big or overly complex. In later teams though, comments were seen as useful. This was mostly because the code was more complex than what I had encountered before and it couldn't always be split up or renamed in a useful way.

Tips and tricks

Thankfully there are a bunch of small things you can do to increase your code's readability. These are a few of the more popular ways in which you can work on the readability of your code. They might be opinionated, who knows! You be you. Feel free to pick-and-mix any that would work for you and your project!

1. Give meaningful names to variables. Make sure they communicate their intent.
2. Don't shorten a variable name if it decreases readability. For example, I know a lot of people who prefer error over e. A short line of code is not always a better line of code.
3. Use a linter or formatter to help people in large teams automate the formatting of their code and avoid common mistakes.
4. Use indentation to make the structure of the code clearly visible.
5. Use comments only where needed and make sure they are brief and to the point.
6. Use a guard clause if you can. This can mean adding an early return on some code that might want to exit if a condition is not met.
7. Try to make functions responsible for one single thing.
8. Do not repeat yourself. If you're using the same code over and over again, abstract it to it's own function so it can be reused. But do keep in mind the earlier bullet of reducing the responsibility of a function to just one thing.
9. Add tests to your code. Tests can help you improve your code and increase readability because when done well, it is self-documenting. Adding a test for different usecases is a wonderful way of addressing any interesting bits and pieces in your code.
10. Remove code if you don't use it anymore! It's awesome to delete code. And tests and source control should be able to cover mistakes. If stuff breaks anyway, I guess you just found something in your code that wasn't covered by your test-suite.
11. Make sure someone understands your code by asking people for code reviews.
12. Make refactoring part of your day-to-day work. If you see something that is unclear to you when you pass by it, see if you can refactor it to something that is more readable. Keep your workspace clean.