3 ms·

In my long experience of writing and reading code I think that comments have mostly been absent. I think that lists of best practice for comments are mostly ir

In my long experience of writing and reading code I think that comments have mostly been absent. I think that lists of best practice for comments are mostly irrelevant because most developers simply don't write them. So, unlike Peter Vogel, I would rather have some bad comments than no comments if that is the price I have to pay for worthwhile comments. What is it about software development that makes people think that yet another list of things to do will make things better? If I were to create a rule regarding comments it would be this: code review should include reviewing the comments.

masklinn 5y ago
> So, unlike Peter Vogel, I would rather have some bad comments than no comments if that is the price I have to pay for worthwhile comments. IME people who write bad comments never write worthwhile ones, so that doesn't seem like a tradeoff, unless you mean a binary choice between allowing or forbidding comments. > If I were to create a rule regarding comments it would be this: code review should include reviewing the comments. Isn't that usually the case? And it's not that hard. The issue I usually hit is that code review should include reviewing the commit messages, and while others may (I really have no idea) github has even less support for reviewing commit messages than they do PR contents.
- jeffreygoesto 5y ago
  > IME people who write bad comments never write worthwhile ones It takes a lot of expertise to extract which information (mostly the "why", sometimes a reference you used while coding) is actually useful as a comment. I also think you need to come across comments that helped _you_ understand other code to learn what good comments are.
  - b3morales 5y ago
    Sure, so people with more experience should be demonstrating good practice here, as in other areas, by writing good comments for the newer people to see and gain experience with.
- petervogel 5y ago
  Notice that this only makes sense if a "bad" comment is somehow still "worthwhile." And we'll incur the cost of writing and maintaining (and, apparently doing code reviews on) bad comments to get there. And that ignores the cost of programmers reading and attempting to process bad comments. Personally,I would rather have well written code than bad comments...and I think programmers can actually create well written code. I question whether we should reasonably expect our programmers, after creating well written code, to suddenly acquire the skillset for writing "worthwhile" comments. Peter Vogel

masklinn 5y ago

> So, unlike Peter Vogel, I would rather have some bad comments than no comments if that is the price I have to pay for worthwhile comments. IME people who write bad comments never write worthwhile ones, so that doesn't seem like a tradeoff, unless you mean a binary choice between allowing or forbidding comments. > If I were to create a rule regarding comments it would be this: code review should include reviewing the comments. Isn't that usually the case? And it's not that hard. The issue I usually hit is that code review should include reviewing the commit messages, and while others may (I really have no idea) github has even less support for reviewing commit messages than they do PR contents.

jeffreygoesto 5y ago
> IME people who write bad comments never write worthwhile ones It takes a lot of expertise to extract which information (mostly the "why", sometimes a reference you used while coding) is actually useful as a comment. I also think you need to come across comments that helped _you_ understand other code to learn what good comments are.
- b3morales 5y ago
  Sure, so people with more experience should be demonstrating good practice here, as in other areas, by writing good comments for the newer people to see and gain experience with.
petervogel 5y ago
Notice that this only makes sense if a "bad" comment is somehow still "worthwhile." And we'll incur the cost of writing and maintaining (and, apparently doing code reviews on) bad comments to get there. And that ignores the cost of programmers reading and attempting to process bad comments. Personally,I would rather have well written code than bad comments...and I think programmers can actually create well written code. I question whether we should reasonably expect our programmers, after creating well written code, to suddenly acquire the skillset for writing "worthwhile" comments. Peter Vogel