Clean Code

Listing 4-5 (continued)
startSending (refactored)

---

67
Bad Comments
Don’t Use a Comment When You Can Use a Function or a Variable
Consider the following stretch of code:
// does the module from the global list depend on the
// subsystem we are part of?
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem()))
This could be rephrased without the comment as
ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem))
The author of the original code may have written the comment first (unlikely) and then
written the code to fulfill the comment. However, the author should then have refactored
the code, as I did, so that the comment could be removed.
Position Markers
Sometimes programmers like to mark a particular position in a source file. For example, I
recently found this in a program I was looking through:
// Actions //////////////////////////////////
There are rare times when it makes sense to gather certain functions together beneath a
banner like this. But in general they are clutter that should be eliminated—especially the
noisy train of slashes at the end.
Think of it this way. A banner is startling and obvious if you don’t see banners very
often. So use them very sparingly, and only when the benefit is significant. If you overuse
banners, they’ll fall into the background noise and be ignored.
Closing Brace Comments
Sometimes programmers will put special comments on closing braces, as in Listing 4-6.
Although this might make sense for long functions with deeply nested structures, it serves
only to clutter the kind of small and encapsulated functions that we prefer. So if you find
yourself wanting to mark your closing braces, try to shorten your functions instead.