Code Smell 75 - Comments Inside a Method

mcsee

Maxi Contieri

Posted on June 5, 2021

Code Smell 75 - Comments Inside a Method

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

  1. Extract Method

  2. Refactor

  3. Remove not declarative comments.

Sample Code

Wrong

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

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

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

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

    // acceptance stage
    acceptWhatHappened();
    lookToTheFuture();
    reconstructAndWalktrough();
}
Enter fullscreen mode Exit fullscreen mode

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();
    postoponeSadness();
}

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

function acceptanceStage() {
    acceptWhatHappened();
    lookToTheFuture();
    reconstructAndWalktrough();
}
Enter fullscreen mode Exit fullscreen mode

Detection

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

Tags

  • Readability

  • Long Methods

  • Comments

Conclusion

Comments are a code smell. If you need to document a design decision, you should do it before the actual method code.

Relations

Credits

Photo by Jason Rosewell on Unsplash


Don't get suckered in by the comments, they can be terribly misleading: Debug only the code.

Dave Storer


This article is part of the CodeSmell Series.

Last update: 2021/06/05

💖 💪 🙅 🚩
mcsee
Maxi Contieri

Posted on June 5, 2021

Join Our Newsletter. No Spam, Only the good stuff.

Sign up to receive the latest update from our blog.

Related

Code Smell 74 - Empty Lines
codenewbie Code Smell 74 - Empty Lines

June 4, 2021

Code Smell 68 - Getters
codenewbie Code Smell 68 - Getters

April 29, 2021

Nude Models — Part I : Setters
codenewbie Nude Models — Part I : Setters

February 20, 2021