Code Smell 05 - Comment Abusers

Code Smell 05 - Comment Abusers

Maxi Contieri

Published on Oct 24, 2020

2 min read

Subscribe to my newsletter and never miss my upcoming articles

Listen to this article

Code has lots of comments. Comments are coupled to implementation and hardly maintained.

TL:DR; Leave comments just for important design decisions. Don't explain the obvius.


  • Maintainability

  • Obsolete Documentation

  • Readability

  • Code and comments duplication.


1) Refactor methods.

2) Rename methods to more declarative ones.

3) Break methods.

4) If a comment describe what a method does, name the method with this description.

5) Just comment important designs decisions.


  • Libraries

  • Class Comments

  • Method Comments

Sample Code



final class ChatBotConnectionHelper {
    //ChatBotConnectionHelper is used to create connection strings to Bot Platform
    //Use this class with getString() function to get connection string to platform

    public $id; //ChatBot Id

    function getId() { //Gets id value

    function setId($id) { //Sets id value

    function getString() {
        //Get Connection String from Chatbot



final class ChatBotConnectionSequenceGenerator {

    private $name;

    function connectionSequence() {


Linters can detect comments and check the ratio of comments / lines of code against a predefined threshold.


More info

Refactoring Guru

What is in a name

Comments as a bad sign

How to comment your code


  • Comments

  • Declarative


Leave comments just for important design decisions. Don't comment a method with a bad name, rename it.


Photo by Volodymyr Hryshchenko on Unsplash

If you have to spend effort looking at a fragment of code and figuring out what it’s doing, then you should extract it into a function and name the function after the what.

Martin Fowler

This article is part of the CodeSmell Series.

Last update: 2021/06/06

Share this