Only one of this comments has value πŸ˜… lovely-dog

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.