The Smell of Your Code

Post date

27 Mar 2010

Filed under

You should not be surprised that a guy who deals with garbage also feels concerned about the smell of your code. If you want to save the click to the Wikipedia article, I can summarize the concept rather quick: Code smell is all those symptons or things you see in code that raises a warning flag in your mind.

If you ever used a static analysis tool to verify your code, you already have covered some of the basis. Those tools will prevent you from shooting yourself with a completely valid syntax (think C):

010   if (entry = valid)
020      result += entry;
030      result = 0;

Once I believed that static analysis was a patch to the ugliness of poorly typed languages whereas properly designed ones never needed to cover for this type of defects. Considering all the factors of smelly code I was wrong. There are plenty of issues in any programming language that can be improved with the right analysis.

The Freudian Approach

Programs must be written for people to read, and only incidentally for machines to execute Abelson & Sussman, SICP

How would you feel if you encounter these variables in someone else code:

SYSTSTS and SYSSTSTS
open and Open
obdoK and obdcK
noEntries and numEntries

Now you might understand the difference between a normal static analysis and code smell. Languages like Ada are not case sensitive because of the second example, but clearly misses the rest. I find the psychological concept quite exiting. We come up with Fortran and C as our first intermediators between the human mind and the machine mind. Other languages followed (functional, logic, object, aspect...) trying to offer a better adaptation of the way we think.

A simple tool with a word proximity algorithm could warn you about those cases. By having a strict naming convention extra checks could be carried. Last line could be further improved enforcing a dictionary of abbreviations.

From a Freudian point of view. This is just the tip of the iceberg. More complex metrics can analyse code complexity, design cohesion, object coupling. All are elements affecting our ability to work with code.

Style matters but no one cares

Most programmers don't use code beautifiers as often as they should, maybe just the good veterans. However simple beautification is only one step towards a unified looking code.

Add naming conventions and syntactic restrictions to the mix, make it part of the compilation process so any fault stops the building process: You will have a tool teaching you the right style. No more discussions about the name of that variable, the position of that bracket or where is that required in the standard. Programmers have too much information to read, a tool enforcing a common style can save a project from overwhelmed programmers who cannot afford learning that long list of apparently silly things.

A strict coding style is greatly underrated. Without a good tool it is easy to ignore some rules, but the larger the project the more important this is. Several huge projects are implemented in a language with a poorly designed packaging system: C. A solid naming convention to emulate a name space is far more important in that case.

However, overall, no matter how good your language is, code is just more maintainable if it looks uniform. At a very minimum, comments should be written in the same human language.

Code metrics on steroids

I believe that the combination of several tools, maybe with the help of XML, can yield far useful metrics for any programmer. Consider this scenarios:

Your bug tracking system counts how many times the class you are debugging had issues in the past. Software projects have a tendency to have trouble maker classes and it is easier to track them if your system knows about your code structure.
Recently some of the automated tests have failed. A VCS can spot recently modified functions related with that test (linking requirements and tests; also the functions used by the test).
Most VCS tools can identify the authors of every line. You could add to your classes a list of experienced programmers, most active ones and modification history. Sometimes it is not that easy to know whom you may ask.
The reliability of one class can be evaluated measuring how often it is used, when was the last modification time, the length of the applied fixes and how old it is. If many people have been used one class without any problem, it should be less likely to some will raise.
When many requirements are implemented within the same class, you start getting the idea that something is failing in your design. Maybe bad coupling. The class tries to achieve too much and its maintenance is clearly troublesome.

Now combine all the above with some classic metrics: your smelliness index!. If just your debugger/IDE could display that information in some smart and attractive format... you should become a very happy programmer!

Evil Side

In some dark corner of company, some manager might have the evil idea of using metrics for the competence appraisal of his/her programmers. That would be like killing the goose of the golden eggs! Software projects don't fail because of the talent of its programmers, they fail because of the competence of their managers. The work quality of a programmer is likely to be affected by the tools, the time and decisions from other people.

Most programmers will love to improve their work and get the best metrics if these prove to be useful. However within a company it will be quite likely that they are told to focus on something else like new features and never in quality refactoring.

Conclusion

Although I started commenting just on code smell, my objective is to raise your awareness on the importance of good metrics. Another of my concerns is the poor connection between different development tools. I hope this inspires you to support some free software project. If you are interested in these missing connections you should read my post regarding XML for compilers.

If you want to read more...

Weinberg98

McConnell04

AHDT99

The Digital Lumberjack

Hacking Code When Life Goes Digital