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.

What exactly is a name? — Part I: The Quest

Maxi Contieri ⭐⭐⭐ ・ Feb 9 '21 ・ 8 min read

#codenewbie #tutorial #webdev #oop

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

        //....

    }
}

Right

<?

final class ChatBotConnectionSequenceGenerator {

    private $name;

    function connectionSequence() {
        //....
    }
}

Detection

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

Relations

Code Smell 75 - Comments Inside a Method

Maxi Contieri ⭐⭐⭐ ・ Jun 5 '21 ・ 2 min read

#codenewbie #tutorial #oop #programming

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

Software Engineering Great Quotes

Maxi Contieri ⭐⭐⭐ ・ Dec 28 '20 ・ 13 min read

#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 ・ 8 min read

#codenewbie #tutorial #codequality #beginners

Last update: 2021/06/06