Kotlin Code Smell 4 - Comment Abusers
Comments are coupled with implementation and hardly maintained.
I've started to work as a software engineer at 2014, however, I started to write code at high-school.
My first language was Assembly, but still, I fall in love with the possibilities to make the computer to do as you wish, shortly after that I started to write in C.
Later on I studied a practical engineering in electricity, and during this time discovered that I preferred much more writing code than design electrical components.
As a result of this understanding I decided to switch and study bachelor degree in computer science in Reichman university, where the focus was of the Java language.
Today I'm working at SumUp using Kotlin, SpringBoot & Micronaut, Cassandra and Kafka
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.
