Timeline for Are comments considered a form of documentation?
Current License: CC BY-SA 3.0
26 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| May 21 at 16:57 | comment | added | gnasher729 | @ctrl-alt-delor There are situations where the absence of code needs to be documented. For example “This exception is not handled because…”. | |
| Apr 10, 2018 at 16:47 | history | protected | gnat | ||
| Nov 8, 2016 at 7:21 | comment | added | gnat | see also: “Comments are a code smell” | |
| Dec 12, 2012 at 1:07 | review | Close votes | |||
| Dec 12, 2012 at 12:48 | |||||
| May 21, 2012 at 0:57 | vote | accept | Dynamic | ||
| May 16, 2012 at 8:37 | comment | added | ctrl-alt-delor | OK I will answer your question, Wouldn't this be considered documentation? Unfortunately yes by many. I have been a developer that has been asked to maintain code that has many comments, that are wrong or useless. They make the code hard to read. You have to ask: does it make it easier to read (maintain/review), how else can I make it easier to read. | |
| May 15, 2012 at 21:02 | answer | added | Mike Hogan | timeline score: 2 | |
| May 15, 2012 at 18:49 | comment | added | Dynamic | @richard I was making it clear that whatever is after the # is a comment. | |
| May 15, 2012 at 18:41 | history | rollback | Dynamic |
Rollback to Revision 3
|
|
| May 14, 2012 at 19:14 | history | rollback | Dynamic |
Rollback to Revision 2
|
|
| May 14, 2012 at 15:24 | answer | added | Chris S | timeline score: 3 | |
| May 14, 2012 at 15:03 | comment | added | Chris S | Is YANGNI "you ain't not going to need it" | |
| May 14, 2012 at 14:47 | answer | added | John Bode | timeline score: 4 | |
| May 14, 2012 at 14:34 | answer | added | user7519 | timeline score: 2 | |
| May 14, 2012 at 14:13 | comment | added | SK-logic | en.wikipedia.org/wiki/Literate_programming | |
| May 14, 2012 at 13:11 | comment | added | ctrl-alt-delor | You are the first customer, but don't over complicate it. | |
| May 14, 2012 at 13:11 | comment | added | ctrl-alt-delor | When ever you wish to add a comment, change your code to be so clear that it needs no comment. Everything is documentation, code is documentation, Comments usualy have no [additional] information, or are wrong. Document the intention the what (code contracts can help with this), and the why. Keep documentation close to the code, use comments. Documentation over Documents: Comments over Documents, Clear Code over Comments. | |
| May 14, 2012 at 13:06 | comment | added | ctrl-alt-delor | Of your 2 comments the 2nd is useless, why not replace $foo with bar. If this is not true then the comment is wrong. The first comment is wrong. It is an assignment. | |
| May 14, 2012 at 10:37 | history | edited | Dynamic | CC BY-SA 3.0 |
added 37 characters in body
|
| May 14, 2012 at 4:59 | comment | added | emory | YANGNI (xprogramming.com/Practices/PracNotNeed.html). Document your code to your satisfaction. Let the customer (if there is ever one) pay you to write the documentation to their satisfaction. Don't worry about what a lot of people you talk to say (unless they are paying you). | |
| May 14, 2012 at 2:50 | answer | added | MathAttack | timeline score: 13 | |
| May 14, 2012 at 2:15 | history | tweeted | twitter.com/#!/StackProgrammer/status/201858161987170306 | ||
| May 14, 2012 at 2:13 | comment | added | user53141 | If you are using a document generation system like JavaDocs or Doxygen, comments are literally documentation. | |
| May 14, 2012 at 0:54 | history | edited | Casey Patton | CC BY-SA 3.0 |
Corrected spelling
|
| May 14, 2012 at 0:11 | answer | added | Oleksi | timeline score: 28 | |
| May 14, 2012 at 0:06 | history | asked | Dynamic | CC BY-SA 3.0 |