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.
Ugh.
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!
Learn more how CodeIt.Right can automate your team standards and improve code quality.
9 Comments. Leave new
Had a dev lead with that same “must comment everything” dictate, and a mandate to use Stylecop to enforce it. After years of fighting that nonsense he finally agreed to make comments on private methods optional, but refused to modify the stylecop rules. So instead, the code is now polluted with stylecop override attributes in place of needless comments.
Wow, that’s pretty awful. Always a bad sign when the coding standard manages to actively make the code less readable/maintainable.
Back in the early 90’s, I took a job at a company in the financial sector. They were VERY mainframe oriented, and PCs were a new thing to them. My team had to maintain one C program, and to write a new one.
The existing C program was possibly the first C program written at this company, where most of the existing code base was in Fortran (and run on the mainframe). It was written by Fortran programmers who had just been told to switch to C. Myself and another person hired right after me were the first two who had had experience writing C code before.
Ok, now that I set the stage, we get to the topic at hand. The documentation standard. It was intended for batch Fortran programs; things that would read a file and spit out a file with no human interaction. It required SEVEN PAGES (on actual paper) for each “entry point” or “module” in the program. The Fortran programs generally only had one of each, so those 7 pages would basically document the whole program. But for the C code, each function counted as a entry point, and required the full documentaion. Page 1 was a title sheet; page 2 had prerequisites, basically the #includes; page 3 had inputs and outputs; page 4 had a step by step summarily of the process it performed etc. Since we tried to code the new program in a structure manner, we naturally had several hundred functions, most only a few lines long. Printing the documentation required three reams of paper.
Futher, since the company Fortran-based coding standard didn’t distiquish between entry point & module, for a while we were told that EVERY FUNCTION had to be in it’s own source file! After some pushback of that, our project leader relented on that one. But we still had to use the company standard file naming system: Our 4-letter department code, followed by a 4-digit sequence number (“DQSD0001.c”, “DQSD0002.c” etc) with no indictation of what function is contained.
(Unfortunately, there was no coding standard which applied to the actual code, which was a total diaster. In the existing program that I had to maintain, I found a 200-line if() statement, within a 300-line for loop, in a 500-line while loop in a 600-line case statement, within a several thousand line switch statement)
Wow… I found myself chuckling along in sympathy by the end, especially when you get to the irony of the standard having nothing to do with the actual code itself. I can recall some pretty mind-numbing requirements that I had for updating design documents and such years and years ago, so I empathize.
I encountered many such coding standard rules that mandated something that might had some reason, in some context, but after that were blindly followed: in one project every class, no matter how small, had to have dozen of C# regions, for every possible visibility:
#region Private fields
#region Protected Fields
#region Protected Properties
#region Constructores
#region Constants
#region Private Methods
#region Protected Methods
…
and so on, for every possible combination.. 🙂
These glorious regions were present in every single class, even if the class has only 2 public methods.. 🙂
Hah! I’ve actually had the same experience. I think somewhere the group had a code snippet floating around that would pre-populate all this stuff for you too. “Efficiency” FTW! 🙂
[…] a fun discussion starter for SubMain: what’s the worst experience you’ve ever had with a coding standard?? Seriously, go weigh in — I know there are some good, facepalm stories waiting to be told in […]
I worked for a company that enforced a standard for if statements that demanded any condition that would be represented as a negative (think if(!found) ) to make it a positive. The result was having no statements in the true-part of the if and placing the good bits in the else-part. I was told that it made it more “readable”. The general form was as follows:
If found Then
Else
doWork()
End If
I tried explaining how bad this was from a branch prediction standpoint and even showed the performance impact in a quick example app. This was further complicated by the fact that the production code was published from the debug build. My suggestion was largely ignored and the standard continues to outlive me in the organization.
Ugh. I feel like I’ve heard of something similar before, but it just amazes me how such things wind up being conceived and then implemented. That sort of thing is hard to take.