Code Smell 75 - Comments Inside a Method
Maxi Contieri
Posted on June 5, 2021
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.
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
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
This article is part of the CodeSmell Series.
How to Find the Stinky parts of your Code
Maxi Contieri ・ May 21 '21
Last update: 2021/06/05
Posted on June 5, 2021
Join Our Newsletter. No Spam, Only the good stuff.
Sign up to receive the latest update from our blog.