I remember the first time I encountered GhostDoc. It was an oasis in a professional desert of soul-sucking conformity.
Okay, wait. Let me back up and explain.
I was working in a custom app dev shop at the time. While working there, I worked on an assortment of apps, big and small, and I delivered to an assortment of clients, big and small. Some had their own internal maintenance devs, and some did not. And yet, in spite of this disjoint, hodgepodge arrangement, the company maintained a single and relatively involved coding standard for dozens of folks on dozens of projects.
The “Professional” Coding Standard
Most aspects of the standard were unremarkable and understandable. So, on the whole, this didn’t bother me. But there was an edict floating around in there that said every method and class, no matter what, needed XML doc comments.
This applied to code being maintained by client developers and to code that nobody would ever look at again. It applied to both API deliverables and to GUI crud apps that nobody would touch again. Why comment everything in this fashion, no matter what? Because it makes us “look professional,” that’s why.
And so I found myself laboriously going back and brainlessly adding comments to dozens of files. You see, I hadn’t known about this standard when I started, so I didn’t bother commenting this forms-over-data thing for which we weren’t even delivering source code. So I had a lot of “work” to do.
Initially, I contemplated writing my own commenting engine. I honestly think I could have done that in less time than it would take to hand comment. But then I figured something like this had to exist already, and my search led me quickly to GhostDoc.
Once I discovered that, I sprayed my code with comments like an exterminator taking care of an ant problem. Then I called it a day.
As I’ve discussed previously, this is NOT how I’d use GhostDoc today or how I’d approach commenting in general. But it got the “job” done, and the powers that be considered “my” comments completely acceptable. Project finished.
Examples of Coding Standard Decrees with Questionable Value
“Brainlessly comment all the things!” is hardly the only encounter that I’ve had with facepalm-inducing coding standards. I’m sure anyone reading can also think of their own experiences and stories. Here are a few more of mine, in no particular order.
- A senior developer I knew would have a hissy fit and “fail” people at code review if they didn’t alphabetize the using statements in all files of a C# codebase…this in spite of the C# team literally telling people not to “waste their time” with this.
- An architect once banned the use of implicit typing in C# because he didn’t understand the difference between implicit and dynamic typing.
- I recall a standard once demanding that we always inherit from a layer of base classes “just in case” we needed that later. This even involved a default scheme where the codebase had CompanyObject that inherited from Object. If you could find no other custom class to inherit from, you inherited from that.
- A guy at one organization hated string literals, dubbing them all “magic strings.” His solution? Everything between two quotation marks had to go inside one single, giant, globally-accessible class simply called “Strings.”
I could go on for a long time since I’ve had a pretty lengthy career. But I’m sure you get the idea. Maybe somebody reading can create a “terrible coding standard ideas” Tumblr.
The Coding Standard Does Have Value and a Place
Before you get the wrong idea, I’d like to make a point. It’s not my intention to throw the baby out with the bathwater. The coding standard does, indeed, have a place.
Absent a coding standard, you can wind up with a confusing hodgepodge of code. It starts to resemble some medieval map of Europe with fiefdoms and a sprawl of local dialects. “Oh, that’s Dave’s code. Good luck trying to understand that — Dave LOVES Hungarian notation and is allergic to white space.”
That creates legitimate technical and business problems. Dave leaves the company, and his colleagues have a miserable time maintaining his code. It’s bad enough grokking someone else’s code when you’re not at all familiar with it. Imagine how much worse it gets if his naming schemes and code idioms are completely alien. “Oh, wait, that’s a field, not a local variable!” Disjoint code makes maintenance more difficult, risky, and expensive. It raises the total cost of ownership for the codebase.
To head this problem off at the pass, teams create coding standards. Such standards are instrumental in creating the phenomenon that extreme programming calls “collective code ownership.” The dialects and inscrutability of pockets of code melt away. Instead, you have a codebase that anyone can feel comfortable editing any part of, at any time.
Coding Standard Gone Wrong
That’s the theory, anyway. And in many shops, that theory does, in fact, work out. But the theory suffers from one problem: it’s easy to mess things up by going overboard.
It’s actually not that far of a walk from “Let’s make a codebase that everyone understands” to “Alphabetize your usings or you fail code review.” But that short walk translates to really big problems.
Software development is a knowledge-work pursuit. That means that it requires deep thinking, creativity, and cleverness. The people doing this work take pride in it and value autonomy for solving those complex problems. A draconian standard can yank that autonomy in a hurry and turn their day-to-day lives into a mind-numbing slog. They go from loving what they do to hating it.
This isn’t just a sad story for the individual. It’s also a terrible outcome from a business perspective. Developers on the team check out and stop giving it their all. Morale suffers and deadlines slip, creating a vicious cycle. The most talented folks get fed up and leave, creating brain drain. Across the board, you wind up with a toxic culture that kills the group’s innovation.
Obviously, a coding standard isn’t the only factor here, and it might be a symptom of a deeper problem. But don’t overestimate the degree to which posing lots of restrictions on people chips away at their morale. I’m sure a lot of you reading can attest to this firsthand.
Proceed on an As-Needed Basis
The solution that I frequently suggest to groups is to make the coding standard document an agreement amended on an as-needed basis. Err on the side of not addressing things, and standardize only when it solves an immediate problem. Are competing variable naming schemes confusing people? Standardize! Is it just someone expressing a personal preference or whim? Leave it out.
In some senses, the more standardization, the better. But standardization comes at a cost, both operational and in terms of morale. So you can’t look at it in a vacuum. Any element of a standard needs to be able to pull its weight and prove valuable.
The alternative is a shop like the one I stayed in briefly, where the standard made my job so mind-numbing that my most interesting prospective problem to solve was automating compliance with it. I left that shop pretty quickly after that, albeit for a variety of reasons. But the fact that draconian standards was one of those, and one that I remember years later, speaks to how powerfully demotivating they are.
What about you? What’s your worst experience with a coding standard? Weigh in below in the comments!