fn()

Code readability

9 July 2022
Code

Code readability is something I find important, but when writing code (especially in a language that I’m reasonably familiar with), it tends to become an oversight. The consequences of code readability often isn’t instantly noticeable if you’re working alone, but when working together with others, it’s important to remember to write code that other people can understand!

Why should we maintain readability?

Making sure that your code is readable sounds like a no-brainer, but at certain points in time — such as when rushing to write code — it’s easy to forget about it. From the little time I’ve had coding here and there, as well as from reading online on other developers’ thoughts on the matter, here are a few reasons why I think readability is important:

What am I doing to maintain readability?

I think it’s a personal journey for every developer; you’ll find your own workflow when it comes to writing code and maintaining readability! For me, maintaining readability comes in three main parts:

Using a standardised code style

I depend a lot on linters and code formatters when I work. I try to use them whenever they’re available; in the languages I currently use, they all offer a linter or formatter, so I don’t have to think really hard about styling my code. I mainly use Visual Studio Code, so many of the languages I use can be used with a linter which has an extension; that makes things easier!

JavaScript and TypeScript

My language of choice at the time of writing is TypeScript, and ESLint is an excellent linter for JavaScript and TypeScript. Along with ESLint is Prettier, a pretty (no pun intended) popular code formatter. Thanks to eslint-plugin-prettier made by the Prettier team, it’s easy for me to link ESLint and Prettier together!

  1. To begin, install ESLint, Prettier, and Prettier’s ESLint config and plugin as dev dependencies.

    # Of course, you can use your Node package manager of choice!
    pnpm i -D eslint prettier eslint-config-prettier eslint-plugin-prettier
    
  2. Next, initialise ESLint in your repository.

    pnpx eslint --init
    
  3. Follow the wizard and remove any plugins that ESLint has installed by default (except for the TypeScript plugin if you’re using TypeScript, obviously), then add plugin:prettier/recommended.

    # eslintrc.*
    "plugins": ["plugin:prettier/recommended"]
    

You should be all good to go!

Python

With Python, I usually use whichever formatter VS Code throws at me; usually, that’s autopep8. There’s also Pylance, and all those come bundled with the Python extension in VS Code. That’s pretty neat!

Utilising comments in appropriate places

Comments are something that can be greatly helpful in explaning certain parts of your code. At the time of writing, though, I don’t think I’ve written that many comments; in a way, I’m not practicing what I preach, but I hope to change that eventually! While writing comments may help, it’s important to know what to write in your commends. To me, that’s definitely a lot more important than how many comments you should litter around the place.

I hope to start adding comments in appropriate places, using the following guidelines to help:

Occassionally reviewing old code

One thing that I like to think may be a good thing is to go back and look at old code. There are several reasons why:

When reviewing old code, feel free to see if there’s anything you can do to help make your code more readable. I haven’t exactly done this as well, but I think that I’d love to give it a try. At the time of writing, I don’t really have that many projects, so it’s a better time than ever to get started!

My questionable code

Over the short period of time I’ve spent learning to code, I think that I’ve written a lot of questionable lines across several languages. I currently play around with Python and TypeScript (or JavaScript) a lot, and I realise that I’ve sometimes written code in a reasonably unreadable manner. Here are just a few examples:

Conclusion

I think that readability is a subjective thing; there isn’t exactly a standard for what makes code readable. For some, it takes a lot of complicated chunks of code to be considered slightly challenging, and for others it’s really easy to get confused. What matters the most is that the code is presented in a way that’s logical to your expected viewer. When writing code, especially one that’s open source, consider what your target audience is: maybe beginners, like those starting to code, or advanced developers? I think that these guiding questions will help me in my journey of making my code more (subjectively) readable:

Spend some time to figure out your own how you code. I think it also doesn’t hurt to revisit old code from time to time, and spend more time scrutinising the way you currently code! Code readability isn’t just good for you, but for whoever else you work with too in the long run — whether it’s if you create open source projects or share your code with someone else.