The Golden Rule for Coding Standards

July 22, 2011

It can be really tedious to define coding standards to the finest detail. The following rule covers about 80% of what you really need to know:

Do unto your code as you would have others do

This rephrasing of the Golden Rule gets to the heart of what standards are all about. Whatever code you write, realize it is something that you are inflicting on other developers further down the line. Think of it as your legacy, because legacy code is what it is. Imagine yourself having to maintain the code (and you may, in fact, have to), and ask yourself if that’s code you can work with.

Also keep in mind that to some degree, you are setting the standards for all work that follows, especially considering the corollary part of this rule:

Do unto the code as others have already done

If code already exists in the project, chances are there a slew of already-established coding conventions. Before writing a single line of code in a new project, take a look around at what’s already there. Ask yourself some questions, like:

  • How is everyone formatting their code?
  • Which libraries are they already using?
  • Are there already examples of how to do what I have to do?
  • What are the overall design patterns, application layers, and so on that are already in force?

and, lastly,

  • Will I have to come up with some new conventions or solutions that others will have to follow?

By looking around, you can save yourself a LOT of time in terms of decision-making for insignificant issues (8-ball decisions), and may come up with examples that solve the majority of your work right off the bat. If you find that you need to create some new conventions, try to follow the “feel” of the code that has already been established. Otherwise, you’re good to go – just remember the Golden Rule!

Advertisements

Varying levels of quality

August 12, 2008

I recently gave a presentation to our development team about Emergent Design, based on the presentation given by Scott Bain at the Dr. Dobbs conference in Chicago. The presentation goes way beyond the use of design patterns to talk about the underlying “principles” (defined more or less as a particular “wisdom” about development) upon which design patterns are based, and specific “practices” (defined as things you should always do because they don’t cost much, and generally embody one of the principles in some concrete way).

Examples of principles include the Open-Closed Principle, and the DRY Principle. Programming by Intention is classified as a practice. He also defines TDD and “Pattern-Oriented Development” as “disciplines”, because they embody principles, but require some level of effort to implement. In the case of disciplines, he says, you should carefully consider the value they provide in your specific situation to see if they make sense for you.

As an architect, it is commonly my responsibility to define standards and best practices, and then make sure one way or another that they are followed. I am often confronted with “special case” scenarios, where for some reason (it’s throwaway code, it’s for a different application, it’s “just a demo”) the developer feels that it would be overkill to follow all our usual standards. This usually goes beyond what Scott Bain defined as disciplines to just about anything: Javadoc, Programming by Intention, writing unit tests, worrying about proper design, using System.out.println(), whatever.

In essence, the question is: is it OK to have different levels of quality for different types of code? Over the years, I’ve found myself waffling on this issue of whether or not it’s necessary follow the standards in these special cases. Recently, I’ve been pretty flexible on the issue. In part it’s because I was introducing some new standards that I felt would be an extra burden, initially, to developers, and I wanted to let them get used to them slowly without them feeling I was being unreasonable about it. In part it’s because I don’t think any practice (or discipline or whatever) should be used blindly without a little thought as to whether or not it’s practical. Allowing for varying levels of quality is one way I could give developers that type of flexibility to decide for themselves.

Giving this presentation has provided me an opportunity to reflect once again on this subject. And once again, I feel I’m swinging back to the other side on this one. There are two reasons for this: the so-called disciplines, and the “killer demo” syndrome.

There’s a reason why “disciplines” are called what they are. It’s because to do them right, to do them efficiently to the point that they really pay off, they require some practice. They also require a conscious decision on the part of the developer to use them. If you’ve ever written code using TDD, you know what that feels like. You’re all ready to start spouting out a brilliant gobs of code that will revolutionize the lives of millions, mow your lawn and pick up the kids from school, get rid of unwanted facial hair, get rid of embarrassing age spots… but then you remember that before all that, you have to write a TEST! Bummer. But for those who have gone through this process, you know that in the end, it’s well worth it, and even enjoyable once you get over that first hump.

Practices aren’t necessarily any easier, at least not until you’ve ingrained them into the way you do your work in general. But these days, I find it hard NOT to write my code using a Programming by Intention approach. It’s just the way I think.

Now, if following disciplines and using best practices takes some practice to get used to, and if in the end you are more productive and produce better quality code, why on earth would you look for opportunities NOT to to get in some good practice? It reminds me of the day I learned how to really type (and not just hunt-and-peck). I knew all about the “home” positions and all that, but had always put off doing it. Then one day, I had a paper to write, and decided that “this is it”. I wasted about two hours worth of productivity struggling to feel out the keys. 17 years later, I’ve never regretted it, and never gone back. My hope would be that programmers would try to follow best practices of their own volition. But when you’ve got deadlines, or when you’re working on a piece of code that you know is heading straight for the recycle bin, perhaps you feel like “cheating” just this once.

As the one who maybe has to play the role of the enforcer now and then, that’s really not a strong enough reason for me to stick my nose where it doesn’t belong. I have enough things to worry about already. The thing is that it can become my problem when that code that was heading straight for the garbage compactor makes a sudden left turn towards the big production onramp, and merges with the flow of traffic right into trunk. This is what Joe Yoder calls the “Killer Demo”, or “Throwaway Code” problem in his Big Ball of Mud article. It happens all the time. I just recently oversaw two or three “demos” that were merged into our application. Some were given the proper time for a complete rewrite, but some were just kinda tidied up, and that’s all. I am also working with some “throwaway” scripts that we’ve been maintaining for about 18 months now. That’s a pretty long time to work with something that was written on the sly.

So, what to do? Should I make an about face and start enforcing standards on all code at all times? I still think developers should be allowed to think for themselves. If they are coming to a different conclusion than I would, it could be a matter of opinion. I also think it’s a matter of culture. If developers aren’t being inspired to do these things for themselves, then maybe there’s more I could do to change that. What was that commandment again? Oh, right. “Show the way”.