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.

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.

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

Code Smell 75 - Comments Inside a Method