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

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

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

Code Smell 03 - Functions Are Too Long

Maxi Contieri ・ Oct 22 '20

#codenewbie #beginners #programming #100daysofcode

Code Smell 74 - Empty Lines

Maxi Contieri ・ Jun 4 '21

#codenewbie #tutorial #oop #programming

Code Smell 05 - Comment Abusers

Maxi Contieri ・ Oct 24 '20

#codenewbie #tutorial #beginners

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

Software Engineering Great Quotes

Maxi Contieri ・ Dec 28 '20

#codenewbie #programming #quotes #software

---

This article is part of the CodeSmell Series.

How to Find the Stinky parts of your Code

Maxi Contieri ・ May 21 '21

#codenewbie #tutorial #codequality #beginners

Last update: 2021/06/05