I despise style guides. Yes, they have their uses but in my opinion, they also cause a lot of harm. I may discuss that in another article but now I am more interested in describing, what I use instead.

The Problem

We strive for guides in a lot of little decisions. And these are not only about naming entities, indentation variants and placement of parentheses. There are a lot more things:

  • When shall we use for comprehensions in Scala and when do we rather call the Iterable-methods (map, flatmap, filter …)
  • In JavaScript how do we handle private properties? Do we neglect them, use Symbols to hide them or start to use an ES.Next proposal?
  • Do we try to embrace the latest language and library features when programming in Java?
  • Which state do we place in React components and which do we keep outward e.g. in a state container like Redux?

Two Ground Rules

I follow two ground rules on how to style my code:

  1. Look at the surrounding
  2. Question what exists

The first one has a higher priority but before explaining how they play together first a description of each:

Look at the surrounding

Almost no code is written in the void. There was other code before. And before writing code, I always know at least a bit about other code in the environment. For example, code that …

  • … already exists in the same file I try to change.
  • … is in other files in the same folder.
  • … is in the same project.
  • … was written in the same language in different projects in the same organisation.
  • … is in the documentation of the frameworks we are using.
  • … was written by strangers that I accidentally see on GitHub.

I use my knowledge about that code and try to style my new code to be as similar as possible.

But not all code is equal: The order of the examples already gave you a clue that some code is closer to my new code and the closer it is, the more relevant it is to me. Closeness is determined by several factors, at least:

  • Location
  • Language / Tools
  • Time
  • People

The first rule helps to raise consistency. This keeps me from pondering long over style issues and eases reading the code afterwards.

But the first rule does not always produce the best code.

Question what exists

The style of the other code was not chosen because it is the universally best style but because it fitted in a certain context. And my context may be different. Maybe even the context for that other code changed and it should be adapted.

Because of this, I am always willing to question the style that exists and I am ready to deviate from present code.

Obviously, those two ground rules conflict with each other.

Balancing the ground rules

When in doubt I first align my new code with the surrounding. This helps me not getting stuck while pondering over style without making progress.

I try to always look again at “finished” code before moving on and when something sticks out like a sore thumb I change that.

There is no hard rule for how long I follow that path but going with my energy usually works out well: If I do not feel well with moving on it is good to review the code. If I do not feel like “enhancing” it any further it is fine to leave it like it is.

Pair programming makes it even easier for me to strike that balance.

Summary

So, when following my two ground rules

  1. Look at the surrounding
  2. Question what exists

the second is important but when in doubt the first one has priority. How do you decide, how to style your code?