Kotlin Code Smell 4 - Comment Abusers

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

Problems

• Maintainability

• Obsolete Documentation

• Readability

• Code and comments duplication.

Solutions

• Refactor methods.

• Rename methods to more declarative ones.

• Break methods into smaller and easier for understanding methods.

• If a comment describes what a method does, name the method with this description.

• comment on important design decisions only!

Examples

• Libraries

• Class Comments

• Method Comments

Sample Code

Wrong

/**
 * ChatBotConnectionHelper is used to create connection strings to
 * Bot Platform Use this class with getString() function to get 
 * connection string to the platform.
 */
class ChatBotConnectionHelper(
    var id: String
) {
    // Get Connection String from Chatbot
    fun getString(): String = TODO()
}

Right

class ChatBotConnectionSequenceGenerator(
    private val name: String
) {
    fun connectionSequence(): Unit = TODO()
}

Conclusion

Leave comments just for important design decisions. Don't comment on a method with a bad name, rename it. Code changes over time, while documentation rarely does, which causes your code to end up with outdated documentation at best, or wrong documentation at worst.

---

Stay updated with my latest thoughts and ideas by registering for my newsletter. Connect with me on LinkedIn or Twitter. Let's stay connected and keep the conversation going!

---

More info

• Refactoring Guru

• What is in a name

• Comments as a bad sign

• How to comment your code

Credits

• Code Smell 05 - Comment Abusers by @Maxi Contieri⭐⭐⭐