Comment contains commented-out code
ID |
objectivec.maintainability.commented_out_code |
Severity |
info |
Remediation Complexity |
trivial |
Remediation Risk |
low |
Remediation Effort |
low |
Resource |
Dead Code |
Language |
Objective-C |
Description
Reports a // or single-line /* / comment whose text is a statement rather than prose - a message send, an assignment, a declaration with an initialiser, a call, a return, or the header of an if, for, while or switch. Documentation comments (///, /* */), commented-out #include and #import lines, and prose that merely mentions a function name are not reported.
Rationale
Commented-out code is code that no longer runs but still has to be read, and a reader cannot tell from the comment whether it is a temporary experiment, a fallback someone means to restore, or a fragment that was superseded years ago. It drifts out of step with the code around it - the identifiers it names get renamed, the API it calls changes signature - so by the time anyone considers restoring it, it no longer compiles. Version control already keeps the old text, with the author and the reason attached.
The following code illustrates the pattern detected by this rule:
@implementation Loader
- (void)load {
// FLAGGED: Comment contains commented-out code
// [self.cache purge];
// FLAGGED: Comment contains commented-out code
// NSInteger retries = 3;
// FLAGGED: Comment contains commented-out code
// self.timeout = 30;
// FLAGGED: Comment contains commented-out code
// if (self.cache != nil) {
// FLAGGED: Comment contains commented-out code
// return NO;
// FLAGGED: Comment contains commented-out code
// configureCache(self.cache);
// FLAGGED: Comment contains commented-out code
/* [self.cache purge]; */
// Purge the cache before loading, otherwise stale rows survive a refresh.
// TODO: decide whether the timeout should be configurable.
// Call configure() before load, see the header for the ordering rules.
// #include <stdio.h>
// #import "Legacy.h"
// Returns NO if the cache is empty (the caller then retries).
/// The loader refreshes the cache and returns whether anything changed.
/** Refreshes the cache. Returns whether anything changed. */
[self.cache purge];
NSInteger retries = 3;
self.timeout = 30;
}
@endRemediation
Delete the commented-out statement. If it records a decision worth keeping, replace it with a prose comment that states the decision and why. If it is work in progress, keep it on a branch rather than in a comment - the history has the text and the reason, and it will still be correct when it is retrieved.