Static analysis tools are automated programs that run a set of rules against source code to produce metrics, and give advice on best practices.

So why does using these tools lead to bad code? 

The Heartache

You’re trying to finish up some down-to-the-wire coding to get it over to your Testers, and your deadline is approaching.  You have this one last class to change and it is a legacy class.  This class was written before the static analysis tools were forced to be run on the code base.  You go in to make a simple change like adding a null pointer check.  You now execute the static analysis tool on the code and you have 30 violations — from incorrect naming of fields to Cyclomatic Complexity greater than the threshold.  You have 2 options here: A) You take the time to fix all the violations, and leave the code better than you got it or B) You take the lazy / easier solution and try and beat the rules — take the easy way out and work around them.  What do you choose?

Reaction to the pain

Depending on what option you chose, you left the code beautiful, a little bit better, or in shambles and worse than you received it.  By choosing option A you decided to be Pragmatic and make the code fix the Cyclomatic Complexity.  Now being the pragmatic programmer you are you need to consider unit testing.  You take the time to understand the violating method and make the appropriate refactoring.  Now you hope the developer before you would have tested this method.  A lot of the times this is not the case or if it is the case, did they write a good test? Did they write a test just to pass the code coverage standard?  Again you have options, you can either take the time to use TDD or you make the refactoring without the test and hope you don’t break anything.

If you chose option B, you decided to hack the code to bypass the rule.  By circumventing the system you are making the code worse, harder to understand, and more likely broken.  You figured out that by extracting pieces of the Cyclomatic Complexity method into other methods bypasses the rule.  This doesn’t truly fix the Cyclomatic Complexity it just hides it from the tool.  Again you have to worry about test or not to test.

Lets look at another less extreme example, you’re now forced to fix a rule that is complaining because the code uses the ‘!’ operand more than max two times mandated by the rule.  You might change the code to “== false” or flip the condition blocks so that it results in true and use the else to catch the false.  This does work on a case by case basis.  However sometimes flipping the if expression to check for true first makes the code harder to read.  By making this change it loses the developers intention.  You are probably making the code worse by trying to beat the system or making the rule happy.  Is the code still easily understood by making this change?  Taking the Dreyfus Model into account will help us determine why a developer would respond in these different ways.

Dreyfus Model

By using the Dreyfus Model we can rate developers into 5 different categories: Novice, Advanced Beginner, Competent, Proficient, and Expert.  Novices are driven by rules and need guidance to complete tasks.  While the Experts are passed rules and use their intuition to drive their decisions.  Something to note about Experts is they can’t explain why they do the things the way they do.

A Novice that is driven by rules will likely fix the problem without hesitation or they could just be lazy and don’t want to push themselves to do the exploratory fix.  Now with Experts they will question the rule violation against their code.  Experts will not just blindly fix the error if they believe their code is correct / a work of art.  This is not their ego talking, but more their experience / intuition / instinct on the subject.  Not all developers are made equal, so why do we think code should be? The Expert will likely not be able to verbally prove their reason for wanting the violation to be suppressed — to them, it’s just clearer and better their way.  By not trusting their instinct you are degrading them.  They are likely going to strike and push back against this rule, toying with the Enforcer.  Forcing rules on the Expert is an incorrect way to treat them and their knowledge.  Rule violations shouldn’t be blindly enforced but taken on a case by case basis.

Learning Tool

I do believe that Static Analysis tools make a great learning tool towards best practices.  Novices, Advanced Beginners could get a lot of benefit from seeing what they did incorrectly when they violated a rule, and learning from it as they progress in their career.

A lot of time you are doing maintenance on code someone else wrote before the tool was enforced to be run.  Now you are held accountable for the fixing the rule when you just came into this class to add a new field.  First off this leads to developers to not wanting to make code changes even though they know it is for the best.  Also you are now held accountable from someone else’s debt.  The original developer might have moved to another team, and hasn’t seen the debt they have incurred.  Now the original developer can’t learn from this experience.  Hopefully when a rule violation is found against someone else’s code it will be shown to them so they get to see the debt they incur.  Developers should be taught to write good code in the first place, but without good mentors that is going to be hard.  Especially when the Experts can’t explain why they do the things they do.

I don’t think that Static Analysis tools should replace code reviews and agile pair programming.  Code reviews should still be done, and require at least another set of eyes on each line of code written.  This will help foster the mentorship and help less experienced programmers with a more experienced developer.

Conclusion

Use Static Analysis tools as a guidelines not a mandate.  Use these tools as training guides for younger developers, and for the advice they are built to give.  Enforce rules on a case by case basis not at an overall perspective.  By enforcing these tools it causes developers to rebel, make the code worse, and not to want to make code changes because they are going to be responsible for fixing the rule that they might have good reason to disagree with — passionately.

Please let us know how have you dealt with these tools or situations in the past.  What pain have you felt from these tools?

References:

Dreyfus model:  Developing Expertise: Herding Racehorses, Racing Sheep by Dave Thomas

Design systems which are capable of change, and you will be much more ready for the future.

Always:

• Program by Intention – “begin by focusing on motivation or desire”
• Analyze the the varying objects and forces in your system, encapsulate them
• Favor aggregation/delegation over inheritance
• Seek the Open-Closed principle – “open to extension, closed to modification.”
• Design to interfaces – “couple to interfaces, not implementation”
• Encapsulate the constructor – use Object.getInstance()
• Encapsulate variation – “what is hidden from you, can be changed”
• Think about how you test a design, when you create it.
• When choosing between two designs with similar cost/risk, consider how easy/difficult it would be to refactor from each to the other, should the need arise.

Think:

Think about the forces of the problem (Do we want to use this pattern / design?)

1. Contextual forces – How will the environment around you and your product affect your system/design?
2. Implementation forces – Will this design work? Is it worth it? Is there a better way?
3. Consequences – What will the results of our actions be? What are the trade-offs?

Think about how you test a design, when you create it. When choosing between two designs with similar cost/risk, consider how easy/difficult it would be to refactor from each to the other, should the need arise.

“Good coupling is Intentional, bad coupling is unnecessary or Accidental“

Never:

• Never allow Redundancy – “Redundancy is DEBT; you always pay for it later”
• Never use ‘new Object()’ notation – Use dependency injection / factories / encapsulation.

Coupling Forces:

1. Identity – One type coupled to the fact that another type exists.
2. Representational – One type coupled to the interface of another.
3. Inheritance – Coupling to a superclass. Changes propagate downward.
4. Subclass – Knowledge that an object is part of a polymorphic set… “knowing the implementation of another.”

Here is his message:

—-

“This is a subject about which there are (obviously) religious wars. If you don’t have it when you need it, you regret it, because you end up spending days or months adding it, to find some problem.

If you have it, its use needs to be controlled. Program flow tracing, or logging variable and argument values, (DEBUG level IMO) is something that one should be able to turn on and off at will (potentially at a subsystem, transaction type, service call, class hierarchy, or function/method call level), and should go to separate log files. The cost of this level of logging can be huge (in both performance and system resources… CPU _and_ DASD, as well as analysis resources).

Logging inputs and outputs of services, where transactions MUST succeed, is a very good idea, if one is to be able to recover from system errors, and one does not have another “back channel path or reconciliation interface” that guarantees you can recover.

When you have business requirements for measuring and reporting and system and component performance, sometimes down the the transaction level, you need a mechanism for doing this that is FAST, failure tolerant, AND does not involve locking exclusions. The mechanism we developed, involved dropping messages into an MQ Series Q, and then having a listener (Message Delivery Bean) on the Q, pick up the messages and write them to a database, which is then dumped nightly and sent to an analitic data store. Data is keep in the operational database (for triage purposes for 45 days on average). If the MQPUT operation fails, the system reports an exception (logged to file system, and sent to an operations monitoring console), and then continues.

Simple systems need less logging than more complex systems. And don’t forget that logging at least service inputs and outputs, can be a good way to prove to a client L2 or L3 triage team that inputs to your service were bad, or proving that the outputs were good. Similarly for called services (as a client). Logging the outputs and inputs, enables one to prove a services was called correctly, but generated bad results or failed. Needless to say, all logs for any transactions, need unique transaction identifiers (TraceIDs) typically, UUIDs a good choices for this.”

—-

It runs in the family:

My father(and mother) has always challenged me to evaluate all sides of a situation, and in the end, I believe his most important message is that every system has different requirements, and every system will require different levels/degrees of logging. You need to analyze what is right for you, because if you mimic someone else’s system blindly, you will surely be missing some chances to get a logging system in place that provides what you need without becoming needlessly cumbersome.

I’ve tried to take this to heart when working on all of my projects with OcpSoft, and my own pet project of PrettyFaces for JSF; needless to say, it’s hard what we do. There’s a lot to think about, and in order to be at our best, we have to continuously analyze as many angles as possible. Logging is no exception.

/**
 * Approximate the square root of n, to within the specified tolerance,
 * using the Newton-Raphson method. This method takes two arguments:
 * @param Double n The number to be square-rooted
 * @param Double tolerance the error tolerance
 * @return Double result of square root operation
 */
public Double approximateSquareRoot(Double n, Double tolerance)
{
    Double root = n / 2;
    while (Math.abs(root - (n / root)) > tolerance)
    {
        root = 0.5 * (root + (n / root));
    }
    return root;
}

It’s my philosophy that if you find yourself writing a comment that describes what a method does, either the method does too much, or you should use that comment AS the name of the method. Try something like this:

public Double newtonRaphsonSqRoot( Double number, Double tolerance )

Method Delegation:

If you need to conform to a standard interface, then delegate! Delegation is your best friend.

public Double approxSquareRoot( Double number )
{
     return newtonRaphsonSqRootApprox( number, 0.0001 )
}

Also… if you don’t want to add a private delegated method, then consider abstracting that behavior into an Operation class that performs the square root.

Object Delegation:

This strategy even lets you change behavior of your square root operations at runtime, at configuration time, and it lets you extend the behavior to use other algorithms without changing your client code. Just make sure that you only expose your interface, because as soon as your clients know about the implementing class, you defeated the purpose of delegating in the first place.

public interface SquareRoot
{
     public Double perform(Double input);
}
 
/**
 * Approximate the square root of n, to within the specified tolerance,
 * using the Newton-Raphson method.
 */
public class NewtonRaphsonApproximation implements SquareRoot
{
    private Double tolerance = 0.001;
 
    public Double perform( Double input )
    {
        Double root = n / 2;
        while (Math.abs(root - (n / root)) > tolerance)
        {
            root = 0.5 * (root + (n / root));
        }
        return root;
    }
}

See, we can even throw in a brief comment where it makes sense to store it.

The Factory:

Look! Now if you want to change the algorithm that calculates your square roots, all you have to do is create a new class that implements SquareRoot, and configure a Factory to provide you with an instance of that class. The possibilities are limitless, really. You can select which type of square root you want to use via a configuration file, dynamic logic, anything:

//where OperationFactory decides which type of SquareRoot to provide.
 
SquareRoot squareRoot = OperationFactory.getSquareRoot();
Double result = squareRoot.perform( 123.2 );

Now it doesn’t matter that we are using NewtonRaphson or TaylorApproximation implementations of SquareRoot. And you still have clear understandable code under the covers.

Final Thoughts:

There are some who will say in response to this article, “you now have extra classes and methods that are making your code harder to understand,” and I say to them:

It all depends on the problem you are solving.

If you are using the newtonRaphsonSquareRoot() method in one place in your entire program, then you might be OK to leave it the way it is, sure. But as soon as you start using that method in other places, you might want to consider making a class to contain it anyway. Don’t just copy and paste your code. Cut and paste in a new class!

The next phase, the Factory, would come when you start using different types of SquareRoot approximations. Factories help hide the details of creation and implementation from the client. Hiding implementation is almost always good.

My article is a response to: this blog. Comment away, so to speak.