On code style and consistency

On code style and consistency

When I started as a software engineer I was puzzled by all those small comments I received in my first code reviews. Colleagues were not commenting about my coding skills. They were commenting about my coding style.

To be honest, I was kind of offended at first. I mean everyone have their style. Why should I change mine? Is it because I was a newcomer? Little I knew that even though at first it looks like everyone should have a personal coding style, if you were to "zoom-out" and see the big picture, coding style in the context of a team has way more consequences.

You see our brain has some (limited) processing power. When reading code, especially written by someone else, we try to comprehend the "logic" of the code by "loading" that code in a mental model. If we could agree on having all the trivial things written using the same style, we would save a few "processing cycles". These "saved cycles" could be spent in those non-trivial things that we need to comprehend. It's pretty much an optimization when working on a team.

Of course, this coding style should not be a decision of the few (or one). Everyone should be on board and agree with most of the coding style decisions. All the decisions ideally should make sense to the team members.

After consensus has been reached in the team about a coding style, there should be strong enforcement for the style to have any benefit. Ideally, this agreed style should be written in some form, for it to be referenced in code reviews if there are doubts. Verbal agreements tend to be a recipe for disaster when it comes to coding styles (e.g. unnecessary back-and-forth in code reviews).

You might say that no single style can capture the needs of every single case that might come up. And I tend to agree. A style should be there to be applied in all the trivial cases. There will always be exceptions to the rule and some flexibility should be allowed. There's nothing worse than changing code or business logic just to "fit" it to the agreed style.

In this era of so many great languages that offer powerful and many expressive options, code styles are more important than ever. There are so many ways to do something trivial using a modern language. I can think of ~4 ways to iterate things. But code styling doesn't have to be strictly for "code logic". It could be just an agreement on the ordering of member variables (e.g. static, then public, then private). These small things can add up and make a big difference when reading code authored by someone else.


Subscribe to our non-annoying-once-a-month digest :)


Consistency for trivial things in code is more important than ever. Whatever can be agreed in advance to do in a certain way, could be considered trivial (for some definition of trivial). If a team can agree in advance on a reasonable amount of things, the more "processing power" the team can spend on the "novel" part of the codebase. Because in the end, that's what matters the most.

Happy coding!

Show Comments