Code Style Traps

Readable code is often compared to well-written prose or poetry. Ideally, code should be a pleasure to read. It’s not only about the words, but also about their structure and formatting. Countless different code styles have emerged over time to improve readability and consistency. Despite that effort, developer teams are still wasting precious energy on code style issues. Let’s look at some common mistakes, so you can avoid them.

Trap 1: No Code Style at All

Not choosing a code style will invite chaos to your code base. It might not matter for your personal hobby project as long as no one else is contributing. However, once you add additional developers, the code base will likely become messy and inconsistent over time.

Trap 2: Code Style Not enforced

What happens when there is no discipline or tooling to enforce a chosen code style? You will get the same chaos as a project that did not choose a code style at all. Even relying on discipline or review processes is risky. Using a code formatter is typically a much better option.

Trap 3: Unconventional Code Style

Sometimes, project leads force their preferred but uncommon code style on a whole team that is not used to that style. This happens because our choices are influenced by personal taste and prior experience with other languages. Picking an unconventional code style is a bit like forcing your team members to wear an uncomfortable outfit every day. Reading code becomes harder for them since they are not used to that style. Writing code may become harder too since a lack of tool support is likely for unconventional styles, requiring manual formatting effort. Even worse, the amount of wasted energy multiplies with the number of involved developers.

How to Avoid Most Code Style Issues

All this harping on mistakes raises the question of what to do instead. In order to get the best results, you should focus on the following aspects:

• Consistency: Avoiding chaos
• Convention: Making use of habits, reducing mental load
• Tool support: Benefiting from automatic code formatting

Below, you can find my decision guideline on picking a code style. The list is sorted by priority. Hence, I recommend picking the first option that matches your conditions.

1. First, check if your programming language comes with a code style included. Python and Go are two good examples. They make it easy for developers to produce consistently formatted code.

2. As an alternative, check which style is recommended by the inventors of your programming language. Consult the official documentation. Look into books written by the original authors. Check standard library implementations.

3. If you are still in doubt, pick one of the most commonly used styles from real-world projects in your language. These can be private company projects or popular open source repositories. Chances are good, that both developer acceptance and tool support will be good in this case.

Summary

By applying the guidelines from above, you can easily avoid 90% of problems around code style issues. The remaining 10% is usually a matter of taste, like when to add blank lines or when to prefer early-return over if / else statements. The point is that we should not waste our time on issues that can be solved with a single decision and a code formatter.

Now, how about you? Are you still bothered by code-style issues?

#SoftwareEngineering #CodeStyle #CodeFormatter #Consistency #Readability