This is a guest posting by Jeff Langr.
“Standards? We don’t need no stinkin’ standards!”
Not only are the individual things we try to base our standards on contentious, but the notion of having standards at all can be contentious, particularly on an agile team.
When someone says the phrase “coding standard,” usually the first thing that comes to our minds is formatting. This nestles us all snugly with very specific visions of braces and tabs dancing in our heads. Many of us feel cozier when things look a certain way; some us feel dread when we see things that offend our visual sense; and some have learned to not give a hoot — in fact, a recent co-worker suggested that we were all professional enough to be able to read code, regardless of the way it looked. Personally, I’ve seen enough languages and differently formatted code that I’ve learned how to wade through it, no matter how horribly it’s presented.
But of course, coding standards can cover so many more things than formatting:
- Naming: Are we using Hungarian notation? (Heck no, though you might be surprised at how prevalent it still is in 2018.) Upper or lower camel case? Snake case? How do we name tests and fixtures? Classes? Namespaces and packages? Parameter names? When are we using nouns vs. verbs? What are the proper domain names to use?
- Test organization: Where do the tests sit? What’s the granularity of the tests? Are tests allowed to produce console output? (No.) Are we using AAA?
- What language constructs are we preferring or avoiding? How do we distinguish among variables of different scope?
- Meta: Are we even writing unit tests? What programming languages are we using? Operating system? Editors? (Please, let’s not start the editor wars again — yet, if we are pairing …) Other tools? These items don’t necessarily impact the coding standard, but they might.
We could debate these standards elements, and so many more, for hours on end. Sometimes there’s not even a clear winner among competing choices: tabs vs. spaces, for example, cleaves the world into two mutually exclusive groups, and never the twain shall meet. Members of each competing faction bolster their stance with solid, unassailable opinions. Some proselytizers wander the hills broadcasting their opinions, whether or not there’s anyone within earshot.
Be forewarned that advocates will sometimes fervently defend an opinion to the point of losing their sense of humor and rationality. I worked with a coach at a customer site who vociferously argued for using tabs. I blurted out, “Well, tabs are just wrong.” The coach seemed hurt and believed I was really an anti-tab zealot, even after I apologized for my sense of humor.
Get TestRail FREE for 30 days!
The Value of Standards
Standards exist for a few reasons. Adherence to standards can help prevent mistakes — this is why “safety braces” exist for single-statement code if blocks:
if (anOddCondition) {doSomeSingleThing();}
The safety brace statement is a long-standing one. My violation of the standard offends developers far more often than not:
if (anOddCondition)doSomeSingleThing();
They’re worried I might accidentally code:
if (anOddCondition)doSomeSingleThing();otherThingApplicableOnlyToAnOddConditionBeingTrue();
I don’t make that mistake. Why not? Because I test-drive. My coding standards have changed. I no longer need the braces to protect me, because I have a better mechanism. Good teams learn how to evolve their standards, particularly when they exist to help prevent errors.
Simple standards have a greater value: They allow us to focus on more important things. Modern life is made less stressful because we have so many implicit standards. Book organization, time zones, electrical outlets, and automobile driving controls are all standardized, to an extent.
Travel to enough places, however, and you’ll find a different set of standards for each of these. When we encounter implementations that vary from the predominant standards we’re comfortable with, we’re taken aback. We waste time figuring out how to deal with the variance, and we might even do something dangerous as a result.
For example, most drivers today wouldn’t be able to get out of the rental car parking lot if given a car with a manual transmission. In the U.S., most new drivers learn on an automatic transmission. We quickly ingrain the location and operation of the brake and accelerator. This allows us to focus on the far more important task of paying attention to the road. Add a clutch and gear shifter to the mix, and we’re dangerously distracted while trying to figure out the new interface.
In programming, deviations from a standard can similarly slow us down, creating small bits of friction as we try to assimilate the logic represented by the code. It’s not atypical to encounter systems that embody a half-dozen different ideas about how to best present the code. Yes, we can grok the code, but we’ll spend a little more effort due to the friction of inconsistency.
Join 34,000 subscribers and receive carefully researched and popular article on software testing and QA. Top resources on becoming a better tester, learning new tools and building a team.
The Cost of Standards
Deriving standards requires effort, of course, as does ensuring adherence to them. Discussions of standards invariably foster an even larger concern: Are they stifling creativity and innovation? This question hints at another cost of standards: We must revisit them often enough to determine what we need to update, lest we lose our ability to move forward or innovate.
As far as creativity is concerned, I imagine that it’s possible for coding standards to stifle it. Strong mandates about C++ programming styles might eliminate the possibility for an elegant (though potentially dense) solution using template metaprogramming. But I suspect these cases are extremely rare.
Code isn’t an art, though it can have artistic aspects. A core element of art is its ability to provoke different emotions and interpretations. Aesthetic beauty is another element of art; code can certainly exhibit this while adhering to standards. One might complain that the boundaries of what is readable kill some opportunities for pretty code. But I hope I never have to maintain code produced by e.e. cummings or submitted as an entry to the International Obfuscated C Code Contest. I just don’t have enough time to figure it all out.
A source file, in contrast, is a collaborative canvas. Teams producing code need everyone to be able to contribute to each canvas — which requires a common understanding of what its content (the code) accomplishes. We might be able to accept and admire aesthetic beauty on a canvas, but we can’t let the beauty get in the way of our ability to understand its meaning.
Agile Standards
I’ve been part of numerous debates about coding standards, and I’ve led a number of sessions to help derive them. Here are a few guidelines I’ve used in the past:
- Not everyone cares what the standard is. They don’t have to attend.
- Participants should come with a short list of things they really care about.
- Set aside an hour, no more, to pin down an initial standard. If no one cares about a specific standards element — for example, how to name constants (upper snake case, upper camel case, etc.) — go with the predominant standard in the codebase or community. Or don’t sweat it at all.
- If the initial standards document can’t be expressed on a single sheet of paper, it’s too much. Hint: Show it in a sample of code.
- The codebase becomes the embodiment of the standard. If we can’t toss the single sheet of paper after a few weeks, something’s not right.
- Every rule and standard is meant to be broken, but we should have a good reason. Breaking a standard might imply a conversation and subsequent transition to a new standard. One way or another, review your standards and your team’s adherence to them at least every few months.
The Most Important Standard
After working with countless developers on countless codebases, I realized I wasn’t as concerned with the specific standards as much as the amount of care the developers put into their code. I have my standards preferences for code, and they’ve evolved over time, but I care most about crafting code that is consistent and accessible. I care because I don’t want other people to waste time deciphering my code.
Perhaps you’re a developer who dismisses coding standards because you don’t need them. No doubt that’s true for many experienced programmers. Think instead, however, that the primary point of standards is for other people:
- You should use descriptive identifiers because you care about other developers who need to understand the code’s intent.
- You should consistently format your code because you care about your teammates who find it challenging to understand otherwise.
- You should use spaces or tabs consistently (well, spaces… come on now!), because you care about Jeff, who gets frustrated when they’re mixed across the source (Yes, you can ignore white space on diffs; that’s only part of the challenge).
It costs little to adhere to a simple set of standards. You should also be gratified to know that you’re making life better for your fellow developer.
We’ve developed community standards around many programming languages. We’ve written countless books promoting language-specific standards. Some of these collections of standards contain hundreds of items — good luck remembering them all!
Ultimately, you need remember only one standard: to care. With each line of code you write, think about how it will be received by the next person who must maintain it. Even if you’re not the caring type, don’t forget that the next maintainer is often yourself.
Article written by Jeff Langr. Jeff has spent more than half a 35-year career successfully building and delivering software using agile methods and techniques. He’s also helped countless other development teams do the same by coaching and training through his company, Langr Software Solutions, Inc.
In addition to being a contributor to Uncle Bob’s book Clean Code, Jeff is the author of five books on software development:
- Modern C++ Programming With Test-Driven Development
- Pragmatic Unit Testing
- Agile in a Flash (with Tim Ottinger)
- Agile Java
- Essential Java Style
- He is also on the technical advisory board for the Pragmatic Bookshelf.
Jeff resides in Colorado Springs, Colorado, US.
Test Automation – Anywhere, Anytime
