Timeline for Are comments considered a form of documentation?
Current License: CC BY-SA 3.0
12 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| May 21, 2012 at 0:57 | vote | accept | Dynamic | ||
| May 15, 2012 at 6:51 | comment | added | martiert | I agree with your arguments, that the "why" is perhaps not as well explained in code, and self documenting code is not enough for customers. Problem I tried to make is that comments are most likely not 100% up to date with the code, as changes in the code sometimes will require a change in the comment. If this doesn't always happen, the comment will no longer document the code exactly. Therefor the code is the only reliable documentation, no mater if the code is self documenting or not. If you need comments, write them at the top of the function instead of inside functions. | |
| May 14, 2012 at 18:43 | comment | added | gbjbaanb | @DonalFellows: not just that but in commercial code, references to bugs or requirements are essential. You often do not know why a piece of code was changed unless you have these links, and they can only be entered as a comment. | |
| May 14, 2012 at 16:40 | comment | added | Steven Evers | Also note that comments, in many languages, are used to generate the actual documentation... so they're are often one and the same. See the MSDN as an example. | |
| May 14, 2012 at 14:48 | comment | added | Donal Fellows | @martiert The problem with self-documenting code is that it doesn't permit references to documentation elsewhere. Some of the best comments in code that I've ever seen have been references to academic papers that explained the details of the algorithm used or the selection of magic constants. No amount of self-documenting is going to help avoid the fact that some, critical, documentation is just plain non-obvious. The “why” often falls in this category, and sometimes the “how” does too. | |
| May 14, 2012 at 13:50 | comment | added | Oleksi | @martiert I used to feel the same way, but I found this doesn't really work as well in practice. All of those "why" comments are much clearer as comments than trying to extract "why" knowledge from code. Certainly self-documentation code can (and should) be used to remove most comments, but sometimes a comment is the simplest, clearest, and most time efficient way to document something. | |
| May 14, 2012 at 13:47 | comment | added | Oleksi | @CrazyEddie I didn't mean to imply that lack of external documentation was good. I've updated the answer to be a little more clear about that. :) | |
| May 14, 2012 at 13:45 | history | edited | Oleksi | CC BY-SA 3.0 |
added 16 characters in body
|
| May 14, 2012 at 13:09 | comment | added | Andres F. | @martiert I disagree. Reality must be a mix of both: actual code shows "what" is done, but not "why". Plain code also doesn't point to external documentation (such as an article describing the clever algorithm you used). This answer does advocate getting rid of redundant comments, so what is the problem? | |
| May 14, 2012 at 7:18 | comment | added | martiert | I really disagree with this, as the only reliable documentation you have is the source code itself. Both comments and "documentation" have to be maintained with the code, which seldom happens. So the only reliable source of documentation is your code! | |
| May 14, 2012 at 6:59 | comment | added | Edward Strange | "For most projects, comments are the primary (if not only) form of project documentation." - tempting to downvote for this but unfortunately it must be admitted as a true statement. I hope though that it is not your intention to claim that this is how things should be. | |
| May 14, 2012 at 0:11 | history | answered | Oleksi | CC BY-SA 3.0 |