Old maps were marked with the phrase "Here be Dragons" to help seafarers steer away from dangerous places; in programming the best way to avoid dealing with bad code is to avoid writing it. Diomidis Spinellis points out 10 giveaways to spot bad code that you (or others) may have written.

From the author of

From the author of

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.