The Path to Cleaner Code

Software engineers spend more time reading code than they do writing code. With tools like Github Copilot, ChatGPT, and other LLMs, it will only become more and more common for engineers to spend time reading code. Knowing how to make code readable, and writing more readable code, will always be important.

But if the code functions, is that not good enough?

NO!

Once code is written, it may exist in a codebase for years. It will have engineers reading it, maintaining it, and thinking about it. If you can make it easier to read and understand, then the time you initially spend will pay dividends down the road.

So keep reading on to see how to make your code more human readable.

Disclaimer

Writing clean code isn’t just about following the style guide of a language. You can follow a style guide, and still have code that is difficult to maintain and read.

But these style guides can also be a good place to start if you are digging into clean code for a specific language. Many organizations such as Google, W3Schools, Python, etc. have style guides for specific languages. You can check those in the resources section at the bottom of this article.

I personally like to use style guides baked into your choice of IDE. Then you and your team can all work on the same repo with the same style guide.

For example, check out setting up pep8 on VSCode

Writing Clean Code

Clean code can be a very opinionated area similar to which IDE is best, or if HTML is a programming language. These are many of my own thoughts on clean code, backed by outside blog posts, articles, and of course “Clean Code” by Uncle Bob Martin.

Variables

Let’s start with the humble variable. The building block of any programming language.

Avoid encodings and data type prefixes

Try to make variables self explaining and pronounceable

Magic numbers use constants and constants in ALL CAPS

Magic numbers are numbers in code that don’t seem to have an apparent reason. This can be a variable dividing by a 37, or another number multiplying by 3.

Lists should use plurals

Avoid using filler or noise words such as Data, The (as a prefix), Object, Info, etc.

Functions

Now let's move on to functions. Functions have more uses than just breaking code into smaller pieces. Functions should be less than 20 lines (and some even argue less than 10!). Small functions make code more testable AND they make code more readable. Smaller functions also can help you follow the principle of least astonishment.

Principle of least astonishment: Most users should never be surprised by the function of a component in the system from its behavior.

Write self documenting code with functions

Keep functions with a single purpose without side effects

Use fewer arguments when you can, or use a dictionary when you can’t

The common practice is to consider a refactor after 3 arguments, but even less is better!

Follow a general verb noun pattern for naming

Comments

We have discussed cleaning code so that we use less comments, but now let's talk about times when comments are needed and appreciated! We can also dive in deeper when maybe we don’t want comments as well.

Remove commented code (usually)

Generally, commented out code should be removed as it will still exist in the git history.

Comment Noise

Too many comments can actually detract the reader, so be careful not to put too many comments in. If you find yourself adding lots of comments, then consider a refactor. But in times of complex code, comments are needed and appreciated!

numpy.einsum is the Einstein summation convention for working with multi-dimensional arrays with linear algebraic operations. I find it incredibly complex and think that you would always want an associated comment.

Conclusion

Yes, clean code is good. But working solutions are usually better than grandiose ones. Don’t stretch to make something clean, and add unnecessary time and effort when something may never be modified again.

Work together with your teams to help define what patterns you like, document those, and learn from each other on how to improve code quality!

Resources

• Clean coding summary
• Clean Code Book
• Clean Coder Book
• Builder Design Pattern (for when you have too many arguments in a function)
• You aren't going to need it paradigm
• Keep it simple paradigm
• Style Guides
  • Google JS Style Guide
  • Python Pep8 Style Guide
  • Google Java Style Guide
  • W3Schools HTML Style Guide