Only one of this comments has value π
Disclaimer
The following is not applicable to a public API. Although a good QuickStart and a good readme are often much more informative than self-generated documentation.
Useless β
// gets the id --> that's just fuck*** noise
fun getId(){ ... }
Its harmfulness is not obvious. But perniciously you end up not reading the comments anymore.
Useful or not, comments are ignored.
Falsely useful β
// returns nothing, fetch remote content and store it in collaborator
fun getContent(){ ... }
Here the comment is useful, because it counterbalances a lack of naming. But it is a palliative, not a solution.
The real solution often involves small refactos, to make the code clearer, more readable.
fun fetchThenStoreContent(){ ... }
Falsely structuring β
fun render(state: State){
// render header
header.foo = state.someData
header.bar = state.otherData
header.fool = state.someData
header.barman = state.placeHereName
...
// render body
body.foo = state.otherData
body.bar = state.yetAnotherData
...
// render footer
footer.foo = state.otherData
footer.bar = state.yetAnotherData
}
As above, comments here are a workaround. Solution is to really add structure. πͺ
fun render(state: State){
renderHeader(state)
renderBody(state)
renderFooter(state)
}
fun renderHeader(state){...}
fun renderBody(state){...}
fun renderFooter(state){...}
And in order to keep my calm I won’t talk about these comments that allow to create collapsible sections. But when they are present it’s often to hide a problem of separation of concerns.
Forgotten β
// pack data for edge network
fun packDataFor5g(data : SomeData){}
Most of the times, grandfather of the useless. Code has lived, been refactored, renamed. But comment remains unchanged.
Epitaphe β
// created by : John Culprit
Here is the name of the first creator of the file. Modified thousands of times, by many developers, whose identity is known only from git.
Don’t attach your name to a piece of software you don’t control.
Anyway git knows! π
Warning β
@Serializable
class Car(){
// serialization unfortunately relies on this typo, don't fix
val engeene : Engine
}
Here comment is clearly warning that code is a trap .
It was clearly placed there to prevent the future developer from making mistakes.
Stack-overflow β
// This piece of code seems weird
// issue -> http://stackoverflow/well_described_issue
// solution -> http://stackoverflow/well_described_issue#solution
Stack-overflow is a powerful database of almost every software issue we can face. Issues are most of the time well described and solution as well. Take advantage of it.
Creative β
Recently I worked for my client for a grid organizer that place items in a grid according to their span size. I tore my hair out when I had to transcribe the test cases drawn on my notebook in name for my test functions.
I finally gave up
/**
* +---+---+---+
* | 1 | |
* +---+ 2 +
* | 3 | |
* +-----------+
* | 4 | 5 | 6 |
* +---+---+---+
*/
@Test
fun `mix 2 with 3 rows 3 cols`() {
val toPlace = listOf(oneByOne, twoByTwo, oneByOne, oneByOne, oneByOne, oneByOne)
val expected = listOf(
oneByOne.at(0, 0),
twoByTwo.at(1, 0),
oneByOne.at(0, 1),
oneByOne.at(0, 2), oneByOne.at(1, 2), oneByOne.at(2, 2)
)
val actual = GridOrganizer(3).organize(toPlace)
assertEquals(expected, actual)
}
Conclusion
Treat comments as code. indented, clean, straight to the point. And exactly like code, the best comments are those you don’t need to write.