Yonatan Karp-Rudin
Yonatan Karp-Rudin

Follow

Yonatan Karp-Rudin

Follow
Kotlin Code Smell 004 - Comment Abusers

Photo by Daria Nepriakhina ๐Ÿ‡บ๐Ÿ‡ฆ on Unsplash

Kotlin Code Smell 004 - Comment Abusers

Comments are coupled with implementation and hardly maintained.

Yonatan Karp-Rudin's photo
Yonatan Karp-Rudin
ยทDec 4, 2022ยท

2 min read

Play this article

Table of contents

  • Problems
  • Solutions
  • Examples
  • Sample Code
  • Conclusion
  • More info
  • Credits

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.

More info

Credits

Did you find this article valuable?

Support Yonatan Karp-Rudin by becoming a sponsor. Any amount is appreciated!

Learn more about Hashnode Sponsors
ย 
Share this