Clean Code – Write Code People Don’t Hate Working On

By Arpad Varga Šomođi

July 27th, 2023 | 6 min read

“It’s easy to write code that a computer can understand. A good programmer writes code that humans can understand”

Martin Fowler

In every programmer’s life comes the time when you stare at a code you have to work on with functions of hundreds of lines, multiple loops and poorly named variables. You spend hours and hours trying to understand it, and if you have to come back to it again months later, you will relive the same ordeal again. You do not want to be the person who writes code that is a pain to work on, so in this blog post, you can learn about clean code and how to achieve it.

“It’s easy to write code that a computer can understand. A good programmer writes code that humans can understand”

This quote encapsulates the essence of clean code really well. We want to write maintainable, understandable and easy-to-scale code.

Making the code clean is not always easy; it takes time to improve it, but it pays off long term by the time saved in the future that was not spent on understanding a messy code. I will tell a few easy tricks to improve your software.

Meaningful names

Names are everywhere in software.

We name our functions, variables, arguments and classes. Because we do it so much, we better do it well. Here are a few things we should think about when naming things:

  • Use Intention-revealing names. A variable, function, or class name should answer all the big questions. It should tell you why it exists, what it does, and how it is used. If a name requires a comment, it does not reveal its intent.
  • Avoid disinformation. Do not refer to a grouping of accounts as an accountList unless it is a List. The word list means something specific to programmers. If the container holding the accounts is not a list, it may lead to false assumptions.
  • Class and object names should contain nouns like Account, Student, AdressParser, and method names should contain verbs like postPayment, deletePage or save.
    •  

How to Write Functions

  • Keep them small. Functions should be small, really small. They should rarely be 20 lines long. The longer a function gets, the more likely it is to do multiple things and have side effects.
  • Your functions should do only one thing. The only thing that function does should be stated in its name. If you follow this rule, it is guaranteed that they will be small.
  • Prefer fewer arguments. The less arguments the better. Avoid passing flags into a function. This is a hint that a function has an IF statement which causes it to do more than one thing – one thing if true and another if the flag is false! Consider fewer arguments. The fewer arguments, the better.
  • Do not Repeat Yourself (DRY principle). Code repetition may be the root of all evil in software. Duplicate code means you need to change things in multiple places when there is a change in logic, and it is very error-prone. You should extract a method whenever you come across a repeated code.

Code Organization & Formatting

  • Group code by their functionality. Related functions must be closed. Related code must appear vertically dense.
  • Declare temporary variables close to their usage.
  • Adapt company/team-wide code conventions. Agree on a common standard for code formatting. Either use an external tool or IDE options for auto-formatting.
  • Make sure the code is ordered as per the calling sequence. The caller should be before the callee.

Comments

While using comments, we should never forget that comments do not make up for poorly-written code. We write a module, and we know it is confusing and disorganized. We know it is a mess, so we write comments. Clear and expressive code with few comments is far superior to cluttered and complex code with many comments. Rather than spend your time writing comments explaining the mess you have made, spend it cleaning it.

Conclusion

The Boy Scouts of America have a simple rule we can apply to our profession: “Always leave the campground cleaner than you found it.”

If we all checked in our code a little cleaner than when we checked it out, the code would not rot. The cleanup does not have to be something big. Change one variable name for the better, break up one function that is too large, and eliminate one tiny bit of duplication. Trust me, the small things will add up with time into a cleaner codebase.

… and PS

I strongly recommend that everyone interested read the book “Clean code – A Handbook of Agile Software Craftsmanship” by Robert C. Martin. It is informative, has an easy-to-read style, and you can improve your code by following the principles explained in the book.

Arpad Varga Šomođi

Arpad is a software developer working on the backend, ensuring everything is running smoothly and as fast as possible. When he's not busy writing code, he loves to watch movies and listen to podcasts. Arpad is also a sports enthusiast and enjoys following football and Formula One racing.