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

Right

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

Code Smell 74 — Empty Lines

Code Smell 05 — Comment Abusers

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

Dave Storer

Software Engineering Great Quotes

This article is part of the CodeSmell Series.

How to Find the Stinky parts of your Code