Timeline for Is it ethical to include opinion based code comments for future developers?
Current License: CC BY-SA 3.0
6 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| Jun 27, 2017 at 18:49 | comment | added | Aaron | @ScottMermelstein feel free to leave fewer comments about "what" and more about "why," but please do not leave zero comments about "what" if the what is complicated and might need to be worked on some day. You didn't insist on zero "what" comments, but I just want to be sure. | |
| Jun 27, 2017 at 18:47 | comment | added | Aaron | The first paragraph is ok, but I disagree with "write a separate document." I want to see the explanation in a multi-line-comment immediately above the algorithm's class or function, even if the comment takes more space than the code that follows it, and even if (or rather: especially if) the algorithm is super-complicated and the comment takes a few pages. | |
| Jun 27, 2017 at 14:59 | comment | added | Scott Mermelstein | Clean code says "Don't comment what you do; comment why you do it." A comment that explains an algorithm could be considered noise; a comment that explains why this algorithm was chosen is almost always useful. | |
| Jun 27, 2017 at 12:28 | comment | added | BЈовић | @PeterTaylor Do you mean something like this: thedailywtf.com/articles/A_Collection_Of_Comments? | |
| Jun 27, 2017 at 11:52 | comment | added | Peter Taylor | Comments may rot, but at least they will be found, unlike a totally separate document. | |
| Jun 27, 2017 at 11:34 | history | answered | BЈовић | CC BY-SA 3.0 |