Timeline for What's wrong with comments that explain complex code?
Current License: CC BY-SA 3.0
8 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| Feb 14, 2017 at 18:37 | comment | added | Syntax Junkie | @OldCurmudgeon: Your reply is close enough to what I was thinking, that I'll just add this comment as an example of your point. While a comment isn't needed to explain clean code, a comment IS good to explain why coding was done ONE WAY OVER ANOTHER. In my limited experience, comments are often useful to explain idiosyncracies of the data set the code is working upon, or the business rules the code is meant to enforce. Commenting code that is added to fix a bug is a good example, if that bug happened because an assumption about the data was wrong. | |
| Sep 8, 2014 at 10:18 | comment | added | gnasher729 | If you need to explain the comments, then surely something is wrong with the comments? Code that needs explaining can do what it's supposed to do perfectly fine. Comments that need explaining are broken. | |
| Sep 5, 2014 at 9:54 | comment | added | OldCurmudgeon | BTW - The Has it run yet comment is referring to the Future and indicates that a get() followed by a check against null detects whether the Future has already been run - correctly documenting the intent rather than the process. | |
| Sep 1, 2014 at 22:51 | comment | added | gnasher729 | A maintainer of that code won't have a context. It's not particularly difficult to figure out what the code does, but the comments are not helping. If you write comments, take your time and concentrate when you write them. | |
| Sep 1, 2014 at 14:59 | history | edited | OldCurmudgeon | CC BY-SA 3.0 | added 178 characters in body |
| Sep 1, 2014 at 14:55 | comment | added | OldCurmudgeon | @gnasher729 - Taken out of context almost any comment will be useless - this code is a demonstration of adding comments that indicate intent rather than attempting to describe. I am sorry that it does nothing for you. | |
| Sep 1, 2014 at 14:48 | comment | added | gnasher729 | The first comment: Has it run yet? Has what run yet? Same for the other comments. For someone not knowing what the code does, this is useless. | |
| Sep 1, 2014 at 11:06 | history | answered | OldCurmudgeon | CC BY-SA 3.0 |