Posted on by & filed under process, programming.

I’ve always been a libertarian when it comes to the writing of code. When the team recently became enamored with coding style guides (e.g. A style guide for Python tests) and asked my opinion regarding the adoption of a particular guide for Javascript, I reluctantly offered the following: “I think there are some good things in there. But I also think there are plenty of things that will have no useful impact other than to create more commits and pedantic comments in code reviews. I think we should start out with a minimal set of guidelines on things that we know have already caused issues and organically add items as they are needed…”

Shortly thereafter I offered up the most debase blasphemy possible in the Python community, “For this reason I’ve never been a big fan of PEP-8 either.”


I could almost hear the thoughts racing… did he actually say that? Heresy! Stone him!

Well, truth be told I’ve never been a fan of standardized spelling either. What’s the point of a phonetic alphabet if you have conflicting spellings and pronunciations? Besides, Chaucer just wouldn’t have the same charm.

I might have to confess that perhaps some of my concern is that I have been writing code the way I write code for a long time and I don’t want someone dictating to me how I should space my arguments. I like the way I do it so go away. It was later pointed out to me that such a blatant rejection of PEP-8 was ironic considering the fact that I write nearly “flawless” PEP-8 code (aside from the ridiculous 79-character limit). I had come across as being hypocritical without realizing it.

I had not expected to have this discussion stir up such a reaction in myself, but I found myself mulling over the issue throughout the rest of the day and again at 3am. Periodically something would come to me and I would dash off a comment in HipChat.

“My basic guideline for writing good code is, if it creates a sense of peace and beauty, use it. If your inner peace departs because of it or it lacks beauty, don’t use it.” I’ll admit it, I’m more right-brained than most engineers.

Later I offered a confession, “I might have to recommend reading Zen and the Art of Motorcycle Maintenance. Pirsig explains how quality is a thing everybody ‘knows,’ but nobody can actually explain. On the other hand, thinking further about style guides and my initial bad reaction, I recall how a daily practice of Tai Chi Chuan requires doing the same form over and over. The form is not Tai Chi per se, but helps one to discover Tai Chi. Likewise maybe a style guide can help one to find the Tao of Javascript as long as it is not used pedantically.”

Someone quipped, “You should write a blog post about that.”

Hmmm, perhaps I will. So instead of hearing about my approach to a Django-like api for Redis, you get to hear my thoughts on code quality. I suspect the other article would have generated more hits, but I find this more interesting.

My fear in the end is that people will focus on the style guide for the sake of the style guide. Code reviewers will use the guide as a hammer to whack fellow coders on the head with. I’ve been in these situations before and I can assure you that PEP-8 is not engraved on tablets of stone.

Pirsig relates a story about his experience teaching rhetoric. I think perhaps his reaction to prescriptive rhetoric is the same as my reaction to a coding style guide. Speaking of his alter ego, he says, “Another thing that depressed him was prescriptive rhetoric, which supposedly had been done away with but was still around. This was the old slap-on-the-fingers-if-your-modifiers-were-caught-dangling stuff. Correct spelling, correct punctuation, correct grammar. Hundreds of rules for itsy-bitsy people. No one could remember all that stuff and concentrate on what he was trying to write about.”

There it is. No one could remember all that stuff and concentrate on what he was trying to write about. That is my fear precisely. I had shared similar sentiments earlier declaring, “My belief regarding code reviews is that they should be focused on higher-level structural or algorithmic issues rather than style. I think it’s far more useful to suggest an alternative algorithm than to point out that you have an extra space.”

And yet somehow I write “flawless” PEP-8. That keeps coming back to haunt me.

The fundamental issue, as anyone who’s ever read Zen and the Art of Motorcycle Maintenance knows, is quality. What Pirsig discovered in his class is that the usual prescriptions do not create quality. One can easily utilize all the classical rhetorical techniques in a piece and still create a work of very low quality, like this dreadful post itself. Likewise, one can follow all the guidelines in the Javascript style guide and create code of very low quality.

Pirsig defined quality by refusing to define it: “Quality is a characteristic of thought and statement that is recognized by a non-thinking process. Because definitions are a product of rigid, formal thinking, quality cannot be defined.” And yet later on he found that once students grasped this concept of quality and experienced it for themselves, the prescriptions taught by formal rhetoric came into their own.

Likewise in my past experience practicing Tai Chi I came to an understanding that the form that is practiced daily and is a prescribed set of movements is not Tai Chi itself, but is only a mechanism through which one can attempt to learn Tai Chi. A practitioner can practice the form every single day and never do any actual Tai Chi whatsoever. Yet it is the door through which one must pass in order to have any hope of true understanding.

I must confess in the end that perhaps there is a place for a coding style guide. I would argue for guidelines that focus on engendering quality without an authoritarian grip on the minor details of style. I prefer to see the character of the contributor coming through in the code. I learn things by reading contributions from my fellow engineers.

Good style is merely the evidence of quality, not the cause of it. A style guide should be a tool that helps us to improve our code, not a penal code. Above all, does it give you peace?

Let us step outside the code for a moment. The existence of a style guide implies a team. While the code is at one level, the culture that produces the code is at a higher level. A project without a culture is a dead project. While a style guide is an important tool to help engender quality, the most important factor in a quality product is a culture of quality and a team that cares about the code. In that regard the Safari Flow team knocks it out of the park.

Tags: code, essay, pep-8, quality, standards, style guides,

Comments are closed.