The Bad Code Spotter's Guide

• By Diomidis Spinellis
• Apr 14, 2006

From the author of
Code Quality: The Open Source Perspective

The ability to spot substandard code is crucial both for programmers and software development managers. As programmers, when we encounter bad code we know we have to take a defensive stance: plan for more development time, expect bugs to crop out of nowhere, and anticipate that small changes may require significant rework. Ideally, we should also arrange for an opportunity to give the code a facelift, refactoring the worse-designed elements and correcting style problems. As managers (for others or of our own work), when we find bad code we need to take a step back and evaluate the situation. Why am I or my group writing this trash? Are there schedule pressures or insufficient incentives for writing brilliant code; is there a need for more training, better design, different development practices?

Here’s a list of 10 giveaways I typically use to spot bad code that I or others have written.

Poor Commenting

Writing good comments is more difficult than writing good code, and therefore identifying code whose commenting is poor is a child’s play. If you see nontrivial functions or methods lacking a comment at their beginning explaining what they do, you know you’re in trouble. The same goes for global variables, class and structure fields, and code blocks implementing a complex algorithm: all should be accompanied by a comment. Note that I don’t expect to see everything adorned with a comment: getter and setter methods, straightforward code, and many local variables are better left to explain themselves.

There’s also the problem of useless comments that simply repeat what is obvious from the name of the entity they explain. A particular thorn here are the elaborate javadoc comments that some sophisticated editors create automatically and some unsophisticated programmers never fill in. Such comments take up valuable screen real estate and distract the code’s reader without contributing something to the program’s understanding.

Finally, there’s also the (relatively less common) problem of excessive commenting. This tends to cause difficulties, because as we programmers maintain the code we often forget to update the comments (especially when there are many detailed comments and we’re unsure about what we’re doing) and this causes the comments to diverge from reality. So, unless you’re programming in assembly language, don’t feel you’ve got to comment every line of code you write.