Timeline for Are comments considered a form of documentation?
Current License: CC BY-SA 3.0
9 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| Oct 19, 2018 at 5:36 | comment | added | Nick Bedford |
I always at least write a single sentence describing in natural english what the function does. I also write class descriptions in a single sentence. // Represents a practitioner at a clinic. or // Gets the available times of a practitioner at a clinic on a specific date.. Code should always try to be as obvious as possible, but frankly, basic documentation is not only good to have, it also separates code segments when highlighted in syntax.
|
|
| May 14, 2012 at 11:08 | history | edited | MathAttack | CC BY-SA 3.0 |
Added clarification to the self documenting code line to reflect the comments.
|
| May 14, 2012 at 10:43 | comment | added | yannis | @MathAttack Most decent IDEs can hide / fold comments. But yes, sometimes they just get in the way. | |
| May 14, 2012 at 10:31 | comment | added | MathAttack | @YannisRizos - You are correct. The one caveat is sometimes tooany comments can interfere with readability but that is the exception. | |
| May 14, 2012 at 7:09 | comment | added | yannis | @DocBrown Depends. I've seen people documenting for loops and I've seen people claiming that a 100 loc of business logic was self documenting. Fact is that excessive comments can't hurt (except if obsolete/incorrect), and if I have to choose between excessive commenting and self documenting code, I'll always choose the first. Of course, I'd pretty much prefer balanced and to the point comments, like Oleksi describes. | |
| May 14, 2012 at 6:32 | comment | added | Doc Brown | @YannisRizos: you may be right, but code which needs lots of comments is almost ever very bad code and could be almost ever written in a manner that it needs less comments. | |
| May 14, 2012 at 4:47 | comment | added | Ptharien's Flame | @YannisRizos More like an unattainable goal than an outright lie. | |
| May 14, 2012 at 4:25 | comment | added | yannis | Self documenting code is a lie. | |
| May 14, 2012 at 2:50 | history | answered | MathAttack | CC BY-SA 3.0 |