Clean Code

What constitutes as clean code? Is it

• Functions that do one thing well?
• Easy-to-understand variable names and abstractions?
• Reduced amount of code duplication?

The thing is, there is no such thing as code that would be considered clean code universally. What Developer A thinks is clean code, Developer B scoffs at. There are tribal wars over what people believe is the correct way to write code. We argue over

• The use of semicolons in JavaScript
• Whether you should indent with tabs or spaces
• Whether you should indent with 4 spaces or 2 spaces

Most of the time, the "arguments" are just for some internet humor.

So is there such thing as clean code? Yes. But what is considered clean code is going to vary from project to project, team to team. Many projects have tooling that make it easy to write code that conforms to a particular style guide.

Use Lint Tools

What is deemed “clean code” is going to vary from project to project. If you’re working on a project with a team, there will probably be a defined style guide and lint tools to help enforce it.

If you are working on your own project that you plan to grow over time, you should take the time to set up lint tooling. You can use GitHub to create a template repository so that you don’t have to worry about setting it up each time.

Tools I Like

The linters I like to use in greenfield projects are as follows:

• For C/C++, Clang-Tidy.
• For Java, I like IntelliJ's ability to reformat and rearrange code.
• For JavaScript, ESLint does a good job.
• For Python, VS Code has good support.
• For Markdown, HTML, JSON, and YAML, Prettier is a good option with good VS Code support.

Once you’ve picked a linter for your project, you now need to configure it with a style guide. Here are some popular style guides I like:

• For C/C++, Google Style Guide
• For Java, Google Style Guide
• For JavaScript, AirBnb Style Guide
• For Python, PEP 8 Style Guide

How to set up lint tooling is beyond the scope of this article. Refer to documentation to learn how to set up the tools you choose.

We Don't All Agree on Code Style

Clean Code by Uncle Bob Martin is a popular book for those interested in learning some philosophies of writing clean code.

However, it is important to recognize what you think is clean code may not be what someone else thinks is clean code. For example, after reading Clean Code, I was excited to start applying the code style Martin taught. The style is extremely modular, with very few lines of code per method. Small classes, small everything.

I was hooked. The thought of getting potential code reuse down the line excited me. I thought the abstractions and names I gave made the code clearer to read and easier to understand.

The developer I was working with didn’t agree. There were methods and abstractions everywhere for everything. You had to bounce around the file to understand what was going on in the code. There was more complexity in how everything interacted.

Reading Clean Code made me aware of common patterns and code smells that come up when writing software. The book does a great job at taking to the extreme what constitutes as clean code and is a great starting point for someone interested in improving their code quality.

However, from that project experience, I learned what I believe is clean code may not be what other developers believe is clean code. In retrospect, an agreed upon style guide could have prevented the issue and enabled a coding environment that made us both more productive.

How to Write Clean Code

To write clean code, your safest bet is to conform to the style guide of the project.

• If the project uses descriptive variable names, then the code you add should have descriptive variable names.
• If the project uses short functions, then the functions you write should be short as well.
• If the project indents with 4 spaces, then you should also ident with 4 spaces even if you prefer to indent with 2 spaces.

Don't get hung up trying to indoctrinate your style preferences on other developers. We all have our different beliefs about what we consider clean code.

Do use lint tooling to automate conforming to the project's style guide. If there is no style guide defined, adopt one. Keep the reader in mind when writing code. Ask yourself, "If I were to look at this code one year from now, would I understand what is going on?"

Try looking at code from one of your old projects. Do you remember how the code works? Is the code easy to understand? If so, great! Perhaps you have written clean code. 😉

Summary

• Read Martin’s book to learn principles of writing clean code.
• Code according to the project’s style guide.
• Use lint tools to help conform to the style guide.