Code Smell 75 - Comments Inside a Method

Comments are often a code smell. Inserting them inside a method calls for an urgent refactor.

7 June, 2023

Contributors

Maxi Contieri

@mcsee

Comments are often a code smell. Inserting them inside a method calls for an urgent refactor.

TL;DR: Don't add comments inside your methods. Extract them and leave declarative comments just for not obvious design decisions.

Problems

Readability
Kiss
Low Reuse
Bad Documentation

Solutions

Extract Method
Refactor
Remove not declarative comments.

Refactorings

Refactoring 005 - Replace Comment with Function Name

Sample Code

Wrong

function recoverFromGrief() {
    // Denial stage
    absorbTheBadNews();
    setNumbAsProtectiveState();
    startToRiseEmotions();
    feelSorrow();

    // Anger stage
    maskRealEffects();
    directAngerToOtherPeople();
    blameOthers();
    getIrrational();

    // bargaining stage
    feelVulnerable();
    regret();
    askWhyToMyself();
    dreamOfAlternativeWhatIfScenarios();
    postponeSadness();

    // depression stage
    stayQuiet();
    getOverwhelmed();
    beConfused();

    // acceptance stage
    acceptWhatHappened();
    lookToTheFuture();
    reconstructAndWalktrough();
}

Right

function recoverFromGrief() {
    denialStage();
    angerStage();
    bargainingStage();
    depressionStage();
    acceptanceStage();
}

function denialStage() {
    absorbTheBadNews();
    setNumbAsProtectiveState();
    startToRiseEmotions();
    feelSorrow();
}

function angerStage() {
    maskRealEffects();
    directAngerToOtherPeople();
    blameOthers();
    getIrrational();
}

function bargainingStage() {
    feelVulnerable();
    regret();
    askWhyToMyself();
    dreamOfAlternativeWhatIfScenarios();
    postponeSadness();
}

function depressionStage() {
    stayQuiet();
    getOverwhelmed();
    beConfused();
}

function acceptanceStage() {
    acceptWhatHappened();
    lookToTheFuture();
    reconstructAndWalktrough();
}

Detection

This is a policy smell. Every linter can detect comments not present in the first line and warn us.

Tip: (Thanks @GreenFieldCoder)

To get rid of comments fast, change your IDE to display comments with red background and yellow text. It will literally scream refactor me when browsing the code.
Also prevents you from writing new comments.