Code Quality – Balancing Code Consistency and Improvement

code-qualitycoding-style

Recently I had a discussion with a colleague regarding code style. He was arguing that your usage of APIs and the general patterns you are using should be as similar as possible with the surrounding code, if not with the the codebase as a whole, just as you would with code appearance (brace positioning, capitalisation etc). For example if I were adding a method to a DAO class in C# I would try to use LINQ where appropriate to help make my code clean and easy to maintain, even if none of the other methods in that class were using it. However, my colleague would argue that I should not use it in that instance because it would be against the existing style of that class and thus harder to understand.

At first I found his position rather extreme, but after thinking it over for a while I am beginning to see his point. With the hypothetical LINQ example, perhaps this class doesn't contain it because my colleagues are unfamiliar with LINQ? If so, wouldn't my code be more maintainable for my fellow developers if I didn't use it? On the other hand, if I truly believe that using such a technique would result in cleaner code, then shouldn't I use it even if it differs drastically from the surrounding code?

I think that the crux of my colleague's argument is that if we all go about implementing similar functionality in a codebase in different ways, and we each think that our way is "best", then in the end the code as a whole just gets harder to understand. However at the moment I still think that if we blindly follow the existing code too much then the quality will just slowly rot over time.

So, to what extent are patterns part of code style, and where should we draw the line between staying consistent and making improvements?

Best Answer

To give a more general answer:

In a case like this, you have two programming "best practices" that are opposed to each other: code consistency is important, but so is choosing the best possible method to accomplish your task. There is no one correct answer to this dilemma; it depends on a couple factors:

  • How beneficial is the "correct" way?

    • Sometimes the new and improved best practice will dramatically increase performance, eliminate bugs, be far easier to program, etc. In such a case, I would lean heavily toward using the new method. On the other hand, the "correct way" may be little more than syntactic sugar, or an agreed idiomatic method of doing something that is not actually superior. In that case, code consistency is probably more important.

  • How big of a problem would inconsistency create?

    • How interconnected is the new code with legacy code? Is your new code part of a library? Does it create an object that gets passed to many parts of the program? In cases like these, consistency is very important. Using a new API, or a new way of doing things in general, might create subtly different results that break assumptions elsewhere in your program. On the other hand, if you are writing a fairly isolated piece of code, inconsistency is less likely to be a problem.
    • How large and how mature is your code base? How many developers need to understand it and work on it? Agreed-upon, consistent standards are much more important for larger projects.
    • Does the code need to run in older environments that may not support the latest features?

Based on the balance of these issues, you have to make the right choice about which route to take. I personally see little value in consistency for consistency's sake, and would prefer to use the latest, best methods unless there is a significant cost to do so.

Of course, there is a third option: rewriting the existing code so that it uses the best methods and is consistent. There are times when this is necessary, but it comes with a high cost.

Related Topic