WonderStyle: Why We Keep Our Code Pretty

Hi. My name is Gemma, and I have a problem.

if ($active)
{
  doTheActiveThing();
}else {
	do_the_inactive_thing();
	if ($special)
	do_the_special_thing();
}

I'm twitching. I twitched reading the source material, I twitched typing it out, and now I'm twitching reading it over.

Away from work (aw who am I kidding), I'm a stickler for proper grammar, correct spelling, and the Oxford comma. I'm one of those luddites who still refuses to substitute u for you and b4 for before in their text messages^*, and who religiously corrects typos in Slack chats. Naturally, that inflexibility translates wholesale to my approach to writing code, and (to my coworkers' dismay) to my expectations for the code I read. Hence the twitching.

Luckily for me and my fellow prescriptivists, caring about form as well as function serves a purpose: Clarity. If writers stick to proper grammar and correct spelling, they don't have to worry so much about confusing their audiences. (Sometimes confusing the audience doesn't matter! Sometimes you're painting a picture, or representing the spoken word, or generally using language to communicate more than facts. Clarity is a lot more important to technical writers than to Gabriel García Márquez.) If programmers stick to a consistent style, we don't have to worry so much about confusing future readers of our code.

Programmers spend most of their time reading

Think about your days spent programming. If they're anything like the days we have at WonderProxy, they look something like this:

1. Read through the requirements for a new enhancement.

• Read through the existing code to see where the new stuff will fit.
• Write some new code.
• Read through the old and new code looking for logic/flow problems.
• Read through the old tests.
• Write some new tests (yes yes, I wrote the code first, sue me).
• Read through the new tests and code to figure out why they're failing.
• Write some code to fix the tests.
• Read through the new code looking for design coherence and efficiency.

That's a list of nine activities, and only three of them involve writing code! And that's for building a new feature! Imagine the sequence if you're bug-hunting for a swapped boolean.

Programmers are trained to notice inconsistency

Treating differences differently is right up at the top of the Best Programming Practices of All Time List that I have in my head and has not to my knowledge been published. You can find recommendations to "encapsulate variation" from decades ago. It's good advice, but it requires us to notice the variation in the first place.

Pushing outside the programming sphere, humans in general are geniuses at pattern recognition. It's what we do. It's why we see Mary in tomatoes and how any scientific discovery at all has ever happened. We recognize patterns, and we notice when the patterns break down.

Programming languages are patterns. When the pattern of the language that you're reading breaks down, you're automatically pulled out of the content to start troubleshooting the pattern. Writers use that behavior to amazing effect, adding color and style and voice and artistry to their work. It's less thrilling in code. For example, here's how I parsed the code snippet from the beginning:

if ($active)
{
  doTheActiveThing();
}else {

wait why is the curly brace over here did i miss a block oh no it's fine it's just different

  doTheActiveThing();
}else {
	do_the_inactive_thing();

uh the indent is different did i miss a block again wait why does my cursor only see one character oh it's a tab it's fine do the underscores mean something different from the camelcases no doesn't look like it

	do_the_inactive_thing();
	if ($special)
	do_the_special_thing();
}

why is there a random if between two functions and also where's its body oh the second function is the if body but why isn't it indented also it's missing the braces because it's only one line and that's technically valid even though it's caused us nothing but headaches over the past forty years and crud i forgot what $special is

Don't get me wrong: It didn't take my brain (or yours) as long to troubleshoot the pattern as it took to read the description of troubleshooting the pattern. That all happens in seconds or less, because we're generally pretty great at patterns. Even so, add all those seconds-or-less together over hours, days, weeks, months, and years, and you end up with some serious cognitive overhead.

Programmers work better without extra work

if ($active) {
  do_the_active_thing();
} else {
  do_the_inactive_thing();
  if ($special) {
    do_the_special_thing();
  }
}

Ahhhhh, happy patterns! Maybe you'd rather have your curly braces on the next line, or you wish I'd swapped the whole thing to camel casing, or your indents use four spaces instead of two, but you can't fault the consistency of the pattern. Nothing in the styling of that code pulls you away from what you're reading.

But Gemma, you protest, it's extra work to make the style consistent! Sure. Maybe. A very little bit of extra work--less, if you set up your IDE to do it for you. Or if you're like me and it's writing inconsistently that makes you do extra work to control the twitching. But remember, we programmers spend most of our time reading code, not writing it. A very little bit of extra work while writing pays off!

In the next installment, you'll learn about the specific style we chose at WonderProxy, and how we maintain it even when we're lazy. If you'd like a preview, check out our customized PHP_CodeSniffer rules!

^* Hilariously, I am entirely on board with sending messages composed of emojis and nothing else. Can't have broken grammar or spelling when there are no grammar or spelling rules to break!