Remix.run Logo
Archelaos 8 hours ago

> neither code nor comments should be tutorials

Why not? To take the example from the article:

  def userCoworkers(u: User): List[Employee] =
    u.departments.flatMap(_.employees) 
Why not add a comment like:

  // Automatically iterates through all the user's
  // departments and assembles a single list of all
  // their employees.
Perhaps a note should also be added explaining why the domain model opted for u.departments and not for something more natural like u.company.departments. And the comment should also explain, why we do not filter for duplicates here.

I insert many such comments into my own code when I use a rare language feature or a somewhat peculiar element of the domain model. This makes refactoring my own code much easier, faster and more bug-resistant. When composing code, it is generally simple and quick to add such a comment, as it is merely a matter of writing down the result of my immediate thought process.

AdieuToLogic 2 hours ago | parent | next [-]

IMHO, comments are required for capturing "the why." Code captures how it works, when it is used, and what it does.

But only the author(s) can capture why it exists via commenting.

bn-l 7 hours ago | parent | prev [-]

Same. And it’s helpful not just for other people but for me also when I’ve forgotten how it works and now there’s no one to ask.