Campbell Ritchie wrote:This is what you r comments ought to have looked like
Honestly, all these comments, the original ones the OP has and these one you offered, are just a lot of code cruft that my brain desperately tries to ignore and push out of the way so I can read the code.
The problem with the OP's end-of-line comments is that it forces me to scan the line left to right to left to right to left, etc. My brain immediately puts a blinder up to block out the right side of the code listing. The majority of these comments are also redundant and unnecessary.
The problem with the interspersed ones that you offered is that they don't align with the code that they are related to and makes for a jagged edge that my programmer's brain abhors. And the comments that the refactoring part of my brain does spend time to read are immediately marked for dismissal and elimination with extreme prejudice because they are either redundant or do not add any more clarity to what the code could potentially express by itself.
My rules of thumb for making comments:
1. Eliminate most of them by making the code more expressive and self-documenting. The code needs to tell a story and it shouldn't need the help of comments to do that.
2. If you do have to comment:
2a. JavaDocs should be resilient to changes in the implementation. That means they should NOT be explaining how the implementation works but rather what the
intent of the code is. Implementation details should be called out like so:
2b. More detailed developer notes are placed at the top of a method and distinctly marked as such. These notes should explain
why you did what you are doing. Ideally, they would reference
unit tests that support the decision. Including some idea
of when the comment was made is helpful for other developers, too.