Standards, Quality, And Two Party Tricks
Here’s a little party trick for true geeks. Take your company’s coding standards. Count the number of times an ‘_’ character appears in it. Multiply this number by the maximum number of lines allowed per function. Add the number of times the word “comment” is mentioned in the document. Divide the result by the number of times the word “meaningful” appears in the document. And finally, multiply the number you received by the number of people in your company who actually write code that fully complies with the standard. [Now, imagine I close my eyes and do some telepathy gestures] your final result is… [drums]… 0.
Now, here’s the greatest thing about this trick. If your result was indeed 0, every geek in the room is astonished by my amazing telepathy powers. But what if the result was different, you ask. Well, think about it. How the heck did I know your company has a coding standard document?
Okay, okay. Because you are all loyal readers, and I just know you can keep a secret, I am willing to break my magician oath, and tell you how I knew that. You see, (are you ready for this…) every software company in the world maintains a coding standards document. If you think your company doesn’t, believe me, somewhere on a long-forgotten location in your storage system there’s a dusty document that carries this exact title.
So, if every company in the world maintains a coding standards document, how come there’s so much buggy, unmaintainable, unreadable, and complex code around?
Well, you really caught me in a good mood, so I’m willing to share yet another industry secret with you. No coding standard in the world will turn your code into quality code. If you want to know why, Tom Harris’ latest post is a good place to start:
“The developer has to understand the warning, standards item, or comment, and then decide:
1. How to change the code to comply, while not breaking anything else
2. When to make the change, in order to meet the deadline for the rest of the features/fixes in the deliveryThe coding standard is no help for either of these decisions. Both decisions are context-sensitive, and require guidance (or mentoring — call it what you want) to decide correctly.”
No set of black-and-white rules can ever define what quality code is. Good code and good design are both context-sensitive. This context changes not only between projects – it often changes even during a project. The only way to master the craft of producing good code and good design is to gain experience in a guided manner through learning and mentoring.
In his article, Tom suggests that any standard must be accompanied by a learning effort. I would take this idea further: a true mentoring effort aimed at nurturing professionalism, gaining experience, and developing intuition, makes any coding standard almost redundant.
Most coding standards are being used as a replacement to professional common sense. They are perceived as a recipe for writing good code. Clearly, they are not doing a great job. In that sense, relying on coding standards to improve code quality is avoiding the real challenge: helping developers develop a genuine professional common sense of their own. Memorizing and following a set of black-and-white rules cannot do that. Sooner or later the hard-coded wisdom of your coding standard will not be able to guide you through the complex and dynamic reality you work in.
So, where does this leave us? Surprisingly, it leaves us with yet another great trick. Are you ready? Take your company’s coding standard (that’s right, I know you have one). Leave your office, and look for the nearest shredder. Shred the document. On your way back to the office, find yourself a professional developer to observe, work with, and learn from. Now wait for the magic to happen…
***
Further reading:
- Coding Standards on the Hitchhiker’s Guide To Software Development.
- The Root Of The Matter
- Mastering Context-Sensitive Domains
October 21st, 2006 at 1:53 am
“Most coding standards are being used as a replacement to professional common sense. They are perceived as a recipe for writing good code.”
How do you format your code? Do you put the “{” on the same line as the “if (…)” or on the next line? Do you write “x=3;” or “x = 3;”? Do you write “if (…) return;” or “if (…) { return; }”? Do you write “this.value” when you access an instance variable or just “value”?
All these things belong in a coding standard. Not because they help writing good code, but to have a common style in team team. This is important if you don’t believe in “code ownership”, but have a team where the code of every module should be known and perhaps even worked on by more than one person, and where people sometimes have to fix bugs in modules they did not write themselves.
A common style helps me to read code that I have not written myself more easy. I can focus on understanding the code instead of “re-formatting” it inside my mind. I am glad we do have a coding standard.
October 21st, 2006 at 6:41 am
Kharos: Code formatting is probably most petty and most irrelevant component of coding standards. Does it change the functionality? No. Does it improve productivity? No. Firstly most developers don’t have to reformat code in your head - any fool can see that if (…) return; and if ( … ) { return ; } does exactly the same thing. Secondly it doesn’t same time on reformatting either - you might save a bit of time when you go in and edit someone else’s code, but that’s peanuts compared with the time wasted by making all the other developers format their code in a way they don’t enjoy. And even if you have abolished “code ownership” (which is a sensible move), you will still find that developers end up spending most of the time working on ‘their areas’ simply because they know it best.
If coding standards have to exist, they should be called coding guidelines and should be represent the acquired wisdom of the group. This is the type of thing you might want to write guidelines on:
* Aviod global variables if at all possible. Exceptions may be made for configuration constants which should always be kept together at the top of the file in one block.
* Try to keep the length of a function to within less than 50 lines. If it’s more than this, refactor into subroutines.
* If you’re writing in a language which doesn’t enforce private methods (like perl) prefix the internal method names with an underscode. That way it’ll be obvious if you’re calling an internal method from another class when you shouldn’t be.
These are just some examples I’ve used before. And the fewer rules you have, the more effective each one is.
June 12th, 2008 at 3:40 pm
I used to agree, 100%. Nowadays I find myself sitting on the fence.
Years ago when the coding standards book first appeared at the place I was working at the time, along with the obligatory corporate comment that this was indeed the “magic bullet” to fix all our problems, I couldn’t bear the pain of a “code review” that ended up turning into a “coding standards review”. A one-hour meeting rapidly turned into a 55-minute discussion over the position of a semicolon and perhaps 5 minutes, if you were lucky, actually looking at what the code did. The reviewee usually considered any coding standard observation as a personal affront. The upshot of it all was usually the review had a negative effect on motivation and morale.
I’ve changed my mind lately, since we now have effective, virtually zero-cost mechanisms to follow the coding standards (such as better formatting in the IDE, and automatable tools such as Checkstyle to produce the reports). People don’t take offense if their ‘violations’ are reported by a machine, and code review time is never taken up with style issues if you can just take it offline and go view the reports in your own time. I’ve found that if the quick view of the reports identifies a ’sloppy’ area, then usually that area contains correspondingly more ‘technical’ problems at well. I am not sure if there has been any recent study to prove this correlation, but it’s a gut feeling that’s grown stronger lately - strong enough that I would happily recommend to a beginning coder to use the automated tools and reports to identify those areas needing attention. The tools allow the coder to focus on more important things; the results seem to indicate where the coder didn’t focus at all.
July 11th, 2008 at 4:53 pm
山本梓