How to sniff your code

Code Smells are symptoms of source code which point to potential problems. Popularized by Martin Fowlers book ‘Refactoring‘, the subject has gained real traction in the software industry over the past few years.

While code smells are well defined, identifying these symptoms in source code is usually a subjective activity. Sometimes an experienced engineer could look at code and ‘feel’ that something is wrong with it. For the inexperienced engineer, identifying code smells may take more sleuthing.

Here are a few activities which should make you ‘feel’ like there may be something wrong. If you find yourself fulfilling these activities, you may have sniffed out a code smell:

Activity #1: You have to scroll to continue reading

How many times did you have to page-down to reach the end of the method or class? Does the code you are looking at spill beyond your view?

You may have sniffed the following smells:

• Long Method
• Large Class

Activity #2: You find yourself performing a "copy/paste/modify"

Are you copying code to add functionality? Are you trying to extend a conditional statement? Are you only going to change one small thing in the code you copied?

You may have sniffed the following smells:

• Duplicated Code
• Conditional Complexity
• Combinatorial Explosion
• Oddball Solution
• Alternative Classes with Different Interfaces

Activity #3: You have to remember something to understand what the code is doing & why

Do you have to write notes to keep track of what is going on? Are you having trouble reading the code? Is the code consistently calling outside objects?

You may have sniffed the following smells:

• Comments
• Inconsistent Names
• Temporary Field

Activity #4: You experience Deja Vu

Does the statement look like the twin of the one above it? Do you feel like you have read this code before? Do you find yourself back at the same method over-and-over?

You may have sniffed the following smells:

• Duplicated code
• Combinatorial Explosion
• Alternative Classes with Different Interfaces
• Data Clumps

Activity #5: Your quick change is taking longer then expected

Is 5 minutes turning in to 50? Do you have to change more then one class to complete your little modification? Does your change reveal insights in to the code which you were not previously aware of?

You may have sniffed the following smells:

• Inappropriate Intimacy
• Feature Envy
• Shotgun Surgery
• Parallel Inheritance Hierarchies
• Solution Sprawl

For details on these and other smells, Jeff Atwood (www.CodingHorror.com) has a nice listing for your review: http://www.codinghorror.com/blog/archives/000589.html

Virtually Standing Up

My teammates & I participate in SCRUM meetings. It is a daily routine that has proven useful and informative. One practice that we have adopted that I also find useful is the ‘virtual stand-up’. If someone cannot attend the meeting, then s/he sends the team an email that acts as a proxy for his or her standup. The content of the message is the same as what they would say during the meeting:

• What was accomplished
• What will I accomplish for the next meeting
• What is blocking me

The virtual standup keeps the team informed & I encourage other SCRUM teams to adopt the process if you have not already.

Identifying Complexity

Complexity breeds bugs. If this is a surprise to you, then stop reading and go buy yourself a copy of Code Complete 2. Read the section titled ‘Importance of Managing Complexity’. This quote from the book drives my point home:

"The bottom line is that programmers who compensate for inherent human limitations write code that’s easier for themselves and others to understand and that has fewer errors." (Code Complete 2, 8)

If you gotten this far, then you likely agree with the statement (or you never read the book and want to learn more). When a software system is complex, it becomes difficult to maintain, modify, & comprehend. So how do you know when a software system is complex? Most seasoned engineers are capable of looking at code and intuitively recognizing that it needs refactoring. Perhaps the code does not flow in a neat, orderly fashion; or perhaps the code is not orthogonal. Nevertheless, no matter how much experience you have, it always boils down to judgment to determine when a method needs refactoring. The kicker is that everybody’s judgment is different, so two engineers may not see eye-to-eye. As a team, you should agree on a standard to identify code that may need refactoring.

So how can you determine if a method is becoming complex?

One technique is to use ‘Cyclomatic Complexity‘. Cyclomatic Complexity is a non-object oriented measuring technique to determine if a class method is performing too many responsibilities. The measurement is an integer value that equals the number of programmatic flows through a method.

Here is what the formula looks like:

Cyclomatic Complexity = number of decision points + number of logical operations + 1

Decision points are conditionals like ‘if’, ‘case’, and ‘?:’ statements, and logical operations are things like ‘&&’ and ‘||’. Here is a simple example of Cyclomatic Complexity in action:

        // add 1 for the 'for'
        for (int count = 0; count < 5; ++count)
        {
            // add 1 for the '&&', and 1 for the 'if'
            if (bClassVar1 && bClassVar2) 
            {
                // do stuff
            }
            
            // add 1 for the 'switch'
            switch (count)
            {
                // do stuff
            }
        }
        
        // add 1 (this is the '+1' in the equation)
        
        // Cyclomatic Complexity = 5

So once you have your measurement, how do you know if your code is complex? As a guideline, the Software Engineering Institute offers the following table:

Cyclomatic Complexity	Risk Evaluation
1-10	a simple program, without much risk
11-20	more complex, moderate risk
21-50	complex, high risk program
greater than 50	untestable program (very high risk)

The table summarizes a Cyclomatic Complexity index in terms of testability (i.e. resistance to change) & complexity. If your Cyclomatic Complexity index is 20 or higher, you will want to consider refactoring the code. Why? The value you calculated is an indicator of how many different paths there are through the method. More paths means greater effort to understand the method. It also means greater effort to test the method & confirm that it functions according to design. With less comprehension & more effort to test every executable path through the method, more defects can remain undetected. In terms of complexity, less is definitely more.

Cyclomatic Complexity, like all metrics, does not dismiss professional judgment. An experienced engineer can preemptively identify growing complexity, a metric cannot. However, if you have inherited code that you are unfamiliar with, reciently made modifications to a class method, or just need to track metrics to determine where your refactoring efforts may be best spent; Cyclomatic Complexity can help you determine if the method needs modification.

The web is full of tools that calculate Cyclomatic Complexity. Google one for your IDE and see what your index is.