Remove Superfluous Comments
| | class Inventory { |
| » | // Fields (we only have one) |
| » | List<Supply> supplies = new ArrayList<>(); // The list of supplies. |
| | |
| » | // Methods |
| | int countContaminatedSupplies() { |
| » | // TODO: check if field is already initialized (not null) |
| | |
| » | int contaminatedCounter = 0; // the counter |
| | // No supplies => no contamination |
| » | for (Supply supply : supplies) { // begin FOR |
| | if (supply.isContaminated()) { |
| » | contaminatedCounter++; // increment counter! |
| » | } // End IF supply is contaminated |
| » | }// End FOR |
| | |
| » | // Returns the number of contaminated supplies. |
| » | return contaminatedCounter; // Handle with care! |
| | } |
| » | } // End of Inventory class |
You’ve probably heard that comments are very important. They are, of course, but only if they add important information (the why). If they don’t, then they’re just getting in the way.
The code above shows the Inventory class that you have seen in a few comparisons before. As you can see by the amount of green text, it contains a lot of comments.
If you just skim the code, you might think that it’s very well documented. And code quality tools will mark this code as “good” in terms of commenting. But that’s just not true.
Most of these comments are superfluous because they only repeat what the code says. Two comments state Fields or Methods, but this is already clear from Java’s syntax. Several other comments are meant to mark the ending of code blocks, such as End IF, End FOR, or End of Inventory class. This is already clear from the indentation.
The most critical comment is probably this one: TODO: check if field is already initialized (not null). Here, the comment really deviates from the code, so this indicates an actual problem.
We can make this a lot more concise! Consider this:
| | class Inventory { |
| | |
| | List<Supply> supplies = new ArrayList<>(); |
| | |
| | int countContaminatedSupplies() { |
| | if (supplies == null || supplies.isEmpty()) { |
| » | // No supplies => no contamination |
| | return 0; |
| | } |
| | |
| | int contaminatedCounter = 0; |
| | for (Supply supply : supplies) { |
| | if (supply.isContaminated()) { |
| | contaminatedCounter++; |
| | } |
| | } |
| | |
| | return contaminatedCounter; |
| | } |
| | } |
We’ve changed the code very little here, but there’s hardly any green text left.
First of all, we’ve deleted all comments that just state what you can already read straight-out from a line of code. All comments that mark the end of a code block (End IF, End FOR, etc.) are gone. The indentation tells us that already, but you’ll be surprised how often you find these comments not only in legacy code, but also in well-known libraries.
We’ve done the same with all comments that highlight the class structure (Fields, Methods, Returns). If you follow the class structure that the Java code conventions set out, then there’s no need for this sort of signposting.
Next, we’ve deleted all comments that just rephrase the code, such as contaminatedCounter++; // increment counter. If a comment doesn’t add anything on top of the code, there’s no point in having it.
We’ve also fixed the TODO comment and added a null and isEmpty() check instead. If you can’t fix a TODO, create an issue in your issue tracker instead where you can discuss and track that problem until it’s fixed.
The only comment we’ve kept is the one that adds information that isn’t obvious from the code. In case the supplies are null or empty, we’ve chosen a graceful continuation by returning zero. We could’ve thrown an exception instead, so there is a reason for including the comment. You could say that it documents a design decision.