The Stray Space
A story about the perils of style guides: what happens when form starts to overcome function
My task was refactoring. That is to say, I wasn't being thrown into the code to make it pretty. I wasn't just doing superficial things like fixing the names of variables and adding comments. I was making a real change! You see, a bunch of different Python modules all ran separately, and they all had a bunch of slightly different threading code that was essentially the same. So, we got the idea to factor out that functionality, and create one super-elegant abstract class that the separate modules' classes can use. For kicks, we figured we'd make it so we can run them all at once from a common class.
Sure! Sounds good. Nothing bad I can say about this. I get to put on my smart developer hat, take this crappy code, and make it good.
Then came a suggestion:
I thought it was a pretty good idea at the time. Yes! Let's do that! Then our code will be even better, right? Readable to the max!
The guidelines set out in PEP 8 are actually pretty reasonable. I've found that most Python code I've written has naturally fallen into the guidelines, with a few notable exceptions, like a habit of writing variable names in mixedCase as opposed to lower_case_with_underscores. Most of PEP 8 is pretty standard stuff, like avoiding extra spaces around parentheses and brackets. Those sort of things.
It's short too. I mean, it's more than just a few paragraphs, but it's no Chicago Manual of Style. You could read it while you ate your sandwich at lunch. Brackets on rye. Mmm.
Nothing. No, really; no problems here. It's a good style guide. It's certainly a good standard to aspire to. When I was going through our code and working on that refactoring, all new code I wrote was done in the correct style. All the existing code in those modules was brought up to snuff. I even endeavored to make most of the lines less than 80 characters long, even though my editor defaults to something like 125. Because that's what you're supposed to do!
When I finished, these Python modules were beautiful and immaculate: fully PEP 8 compliant. They'll be on display in the Museum of Modern Art this spring. I crafted the final commit message and sent it up to the repository, working perfectly and looking sharp.
But those modules were the only Python code that we'd decided to fix up in terms of PEP 8. Everything else was to be left alone. I was disappointed, but I understood. I tried to get on with my life. But having spent a few days in the land of beautiful code, I noticed that coworkers' checkins started to seem a little… off.
Someone's tuple had no spaces after the commas. Someone else's dictionary-ending curly brace was on the next line. One might say that it looked better that way, but in my heart I knew they were wrong. After all, my PEP 8 checker said so! Each violation of the style guide was like a shot through my chest. These poor, misguided coworkers. They just don't know any better. I have to teach them somehow. I know! I'll just go fix their code for them!
And I did. A few times I went to a file to make a tiny one-line bugfix, and ended up with a diff that scrolled off the screen. The meaningful change was buried in a sea of whitespace changes. But that was okay, I told myself, because now that file was tasteful and aesthetically pleasing. It was the right thing to do, right?
I suppose I realized that something was wrong after reviewing one particular changeset. One developer had checked in a one-liner: they added an explanatory comment between two lines of code. But it just so happened that the hash mark that began the comment was indented one extra space. A stray space had wiggled its way into a commit by accident.
No, I thought. No, no, no. I couldn't deal with that extra space. It was so totally off! It broke the visual flow of the code!
But I knew I couldn't just check in a change to get rid of that space. It wasn't even on a line of real code!
Hmm. Time for a little introspection. Let's maybe do an exercise with whys.
Ah-ha! An epiphany! It turns out that the reason is simple: once you get past a certain point, code style just doesn't matter. The purpose of code style guidelines is to make sure that everyone can read and understand a common codebase. To be so strict with adherence to guidelines, as I had been, is ridiculous. It's even more so for a language like Python, which reads like pseudocode no matter how sloppily you write it.
We developers love to get caught up in the little things like code style. But the right way to go about it is not to tape the guidelines above your monitor with rays of light made of yellow construction paper surrounding it. Your style guide is not the final word. Just read the thing and get on with writing code. Your fellow developers will thank you. •
