DEV Community

loading...
Cover image for Code Smell 05 - Comment Abusers

Code Smell 05 - Comment Abusers

Maxi Contieri
Learn something new every day. - I am a senior software engineer working in industry, teaching and writing on software design, SOLID principles, DDD and TDD.
Originally published at maximilianocontieri.com Updated on ・2 min read

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.

Problems

  • Maintainability

  • Obsolete Documentation

  • Readability

  • Code and comments duplication.

Solutions

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.

Examples:

  • Libraries

  • Class Comments

  • Method Comments

Sample Code

Wrong

<?

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

        //....

    }
}
Enter fullscreen mode Exit fullscreen mode

Right

<?

final class ChatBotConnectionSequenceGenerator {

    private $name;

    function connectionSequence() {
        //....
    }
}
Enter fullscreen mode Exit fullscreen mode

Detection

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

Relations

More info

Refactoring Guru

What is in a name

Comments as a bad sign

How to comment your code

Tags

  • Comments

  • Declarative

Conclusion

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

Credits

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

Discussion (8)

Collapse
1e4_ profile image
Ian

Depends on if you generate documentation through annotations in which case comments are good and very much needed, not the single line ones but phpdoc.

If you give examples of code I'd try and adhere to general standards which include not starting a file with <? But <?php. For beginners it's pretty crucial to not let them assume it's good to start with short tags 👍

Other than that nice tip

Collapse
mcsee profile image
Maxi Contieri Author

Thank you very much for your comments

I choose <? instead of <?php because language is accidental.
I don't want to be tied to a particular language, could have been Js, Java etc.
I don't want articles targeted to php community. That's why I don't suggest php doc.
I don't think documentation is useful if you are declarative enough

Collapse
1e4_ profile image
Ian

Everything in this post points to PHP.

I heavily disagree with no documentation. Just because you know what's going on doesn't mean someone that comes to a project later on.

Thread Thread
mcsee profile image
Maxi Contieri Author

That's why you need to write declarative methods, classes and attributes.

Methods are alive. They are maintained . They run with the tests.

Nobody maintains documentation. And nobody reads them

Thread Thread
mcsee profile image
Maxi Contieri Author

That's why tests are for.

They are alive, they are maintained and they don't lie

Collapse
moopet profile image
Ben Sinclair

I can't see any difference between your "wrong" and "right" examples.

Collapse
mcsee profile image
Maxi Contieri Author

There's a bug in devto with embeded code and caches. I've updated the article and inlined code. Can you check it out ?

Collapse
moopet profile image
Ben Sinclair

Yeah, it looks right now.