Geeks With Blogs
Chris Falter .NET Design and Best Practices

We software engineers and architects sometimes feel like the rope in a tug-of-war.  Pulling from one side is the short-term goal of delivering functionality, preferably yesterday.  Indeed, our customers cannot justify paying for our services unless we deliver a working product, better and faster than our competitors.  Pulling from the other side, however, is the long-term goal of quality.  If our code becomes too disorganized or hard to understand, we cannot long remain in business, because we will no longer be able to deliver timely new functionality. But we may not even last long enough to see our code melt down in entropy; our customers might uninstall our buggy products first!

Balancing these two forces can be very hard.  As a developer, I want to be a hero and deliver, but I also want my code to meet at least a minimal quality standard.  So it would be useful to have a rule of thumb to know when my code is at least minimally ready to check in. Quality, after all, is hard to measure; like beauty, it is often in the eye of the beholder.  What should go into a useful rule of thumb, then?

I think the minimal standard can be expressed as being able to answer yes to the following three questions:

  1. Is my code easy to understand?
  2. Is my code free of duplication?
  3. Is my code supported by unit tests?

Let's examine each of these briefly.

Is my code easy to understand?

Code that is hard to understand is hard to work with in so many ways.  Consider these points:

  • If your code contains magic numbers or constants, how will your fellow programmer be able to understand what's going on?  Use enums or named constants instead. 
  • If you write a function that is 300 lines long, how will your fellow programmer be able to understand at a glance what it's supposed to do?  Refactor long methods into a series of calls to smaller, cohesive methods.
  • If your objects and methods do not incorporate the ubiquitous language of the domain you are working in, how will your fellow programmer be able to relate your code to the functionality that needs to be fixed or extended?  Make sure your objects and methods have good names.

Is my code free of duplication?

Cut-and-paste coding makes code extremely difficult to navigate and modify.  How can your fellow programmer know which code paths handle which conditions?  And what if, God forbid, the duplicated code has a bug or otherwise needs to be modified--how will your fellow programmers know that they have identified all the places that need to be modified, and that each location has the correct change?  Learn to use design patterns to avoid duplication in object-oriented code, and  to use functions for procedural or functional languages.  Apply the DRY principle ("Don't Repeat Yourself") relentlessly!

Is my code supported by unit tests?

Unit tests help prevent regressions.  They document the code under test by showing how it gets used.  They help improve the design by making sure that a class does not have too many responsibilities, and that its dependencies are not out of control.  Of course, unit testing is a subject that could occupy many blog posts, as I myself have proven.  Just make sure you're writing them early on in the development cycle!

Why these three?

There may of course be situations where the quality standard should be even higher.   I have not touched on important subjects like system performance, scalability, traceability, and error handling, for example.  However, the requirements in these areas may change from project to project.  The standards we have examined, though--readability, freedom from duplication, and unit tests--apply to all but the most trivial of systems.  While you would like your code to be 100% defect free from the moment you check it in, that is not a realistic goal.  The critical goal in maintaining the long-term viability of your code base is to be able to fix it, improve it, and/or extend it with a minimum of friction.  And these three questions can help you know whether you can do so successfully:  

  • Months or years later, you (and your colleagues) will be able to work with your code--if it is easy to understand.
  • You can modify it without fear of missing some duplicated code that might also require the change, or of implementing the change incorrectly/differently in a duplicate code location--if you have followed the DRY principle.
  • You can modify it with minimal fear of introducing a regression that doesn't get detected by manual testing--if you have supported it with unit tests wherever possible.

So that's my opinion.  What's your take?  Are these the right 3 questions to include in a rule of thumb?  Leave a comment and let me know what you think...then go and write some more great code!


Posted on Wednesday, June 23, 2010 12:55 AM Coding Practices and Design Patterns , Software Architecture | Back to top

Comments on this post: When Is Code Good Enough? (A Rule of Thumb for the Perplexed)

No comments posted yet.
Your comment:
 (will show your gravatar)

Copyright © Chris Falter | Powered by: