Code for humans (Part II)

In part I. of this article, I talked about the importance of writing code that is easy to understand for humans. I deliberately left out actionable advice because there is no definitive set of guidelines or rules to follow when it comes to writing code for humans. However, I understand that talking about a problem without offering any solution can be disappointing so here is a list of things to watch for when writing readable code.

Keep in mind that this list is non-comprehensive, might change over time and somewhat opinionated. Opinionated in the sense that some developers might not agree with certain points (and that's okay), but these are things that I see applied by highly effective software developers whom are usually considered to be excellent by their peers.

Practical tips for writing human-readable code

Avoid abbreviations

I have worked with many old-timers who fanatically used abbreviated naming in their code. Whether you like it or not, abbreviating adds an extra mental challenge to the process of reading code. No one likes to stop on every line of code to try and decipher the meaning behind a variable or a function. I think shortening and abbreviating are a leftover from a bygone era where file size was a considerable issue.

Think about it this way: stretching it to extreme measures, abbreviation quickly looks like obfuscation; a process that is meant for making code unreadable for humans.

Be consistent with the project

Whether it is code formatting or naming, managing dependencies, etc. always be consistent with the project you're working on. It might not be what you prefer or what you are used to, but a consistent codebase is key for human readability.

If the project does not have a coding guideline, be consistent with the language. Many modern languages have language-specific coding standards. Use them.

I've seen codebases where you could tell what team member wrote a piece of code just by looking at it. While it spares you a blame query on your version control system, inconsistent code is hard to read. Imagine reading a book where the perspective changes from paragraph to paragraph or the way the dialogue is formatted.

Convey intent

Your code needs to convey the intent behind it. Using best practices is not only good for not reinventing the wheel all over again. Developers are familiar with common patterns and best practices so by using them, you immediately convey a bunch of information about your approach to the problem without a single line of code comment.

Separate concerns

Separation of concerns is a deep topic and is out of the scope of this article. However, separating concerns comes with the emergent property of having bite-sized logic to understand. If a class only does one thing, the scope of the problem is limited, so understanding its functionality is easier.

This also puts a virtual constraint on how big a class should grow. If a class is too big, it most likely takes on more responsibility than it should. Obviously, the bigger the class, the harder it is to understand.

Use jargon

Get familiar with common language used in coding and use jargon in your code. Don't try to come up with fancy names for everything (I was guilty of this too), use naming developers already familiar with. It is similar to the advice above, using common language will reflect intent without needing to process your code further.

Use comments properly

Ideally, the code should speak for itself. That is not a remark against code documentation, if anything, we need more high-quality documentation. However, there is no need to describe code logic in human language too; it is redundant. If you feel like you need to describe the logic behind an if statement in a comment, you should most likely extract that logic into its own little island and use actual code to reflect its purpose.

Use comments to convey information that is contextual, needs explaining or describes usage. The last time you fixed a bug with a code so shameful you felt like you needed to write an apology letter explaining your actions to every future dev looking at it? Comment away.

Watch for indentation

When it comes to code flow in general, each level of indentation has contextual variability since we usually indent after control flow statements such as ifs, fors, etc. When you are 7 tabs deep in a code, you probably have a bunch of run-time variables to keep in mind. Try to structure your code and logic in a manner that reduces this kind of cognitive load.

Indentation is also a tool. Use it to make your code more structured but follow the project's coding guidelines first.

Use empty lines

Reading a huge block of code is like reading an article that is not broken into paragraphs. I've seen so many developers code like they have a short supply of line breaks. Huge chunks of code are hard to process, and our brain needs visual separation to digest written information more easily.

It's like trying to talk without breathing. Your code needs to breathe. Break your code into small logical blocks and use line breaks to separate them.

Don't mix English

This one's for non-native English speakers like myself. I have a hard time reading code that is written in half English half my native language. Be consistent with the language and preferably use English. Switching language context when reading code is an unnecessary cognitive overhead.

Use tabs over spaces

Just kidding, use whatever you prefer. Kidding again, use whatever the project you're working on uses. Don't you remember? Consistency is key.

In conclusion

Writing code that is easy for humans to process is not an easy skill and it takes practice. I'm still learning it and I think I always will. AI tools will come in handy to ease our job when it comes to understanding codebases, especially huge ones. You can just simply ask something in natural language and the model will analyse the code and answer it for you. If you take out the understanding part from the whole development process, there is no need to be gentle to humans. However, that is not a reason to not care about how well your code is read by other developers. At least not for now.