Timeline for How to deal with tautology in comments? [closed]
Current License: CC BY-SA 3.0
44 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| Oct 20, 2015 at 17:37 | history | closed | CommunityBot durron597 Ixrec | Opinion-based | |
| Oct 17, 2015 at 3:34 | review | Close votes | |||
| Oct 20, 2015 at 17:37 | |||||
| Apr 16, 2012 at 13:56 | vote | accept | Tamás Szelei | ||
| Apr 4, 2012 at 21:15 | answer | added | Chris Allen Lane | timeline score: 3 | |
| S Mar 30, 2012 at 16:58 | answer | added | Warren P | timeline score: 2 | |
| S Mar 30, 2012 at 16:58 | history | made wiki | Post Made Community Wiki by Warren P | ||
| Mar 30, 2012 at 14:12 | comment | added | Tamás Szelei | @Paul, there is no picked answer at the moment (nor when you commented). I initially picked one, but removed the tick because there was a lot of interest towards the question and I didn't want to discourage anyone from answering. | |
| Mar 30, 2012 at 13:15 | comment | added | Paul | @CodyGray has the correct answer... The picked answer is not the correct answer... | |
| Mar 30, 2012 at 11:30 | comment | added | ctrl-alt-delor | Code in such a way as to make the comments useless tautologys, then remove the comments. Use comments for why, use comments in cases where the language is week and can not express something (pre/post conditions). | |
| Mar 30, 2012 at 10:29 | comment | added | MrTJ | There are different comments. Some types between source lines, let's call them "inline comments" help you to understand how your code works. Some other types, like that one in the question, are API documentations that help the user of your API to understand how to use your code. Whereas in the first case there is not much sense to use tautology, in the second case there might be. | |
| Mar 30, 2012 at 0:33 | answer | added | Scott Whitlock | timeline score: -1 | |
| Mar 29, 2012 at 23:41 | comment | added | Chance | "A comment like that is useless; what am I doing wrong?" If you code so that the comment is useless, you are doing something right. | |
| Mar 29, 2012 at 23:29 | answer | added | Terry Bollinger | timeline score: 3 | |
| Mar 29, 2012 at 22:48 | comment | added | Keith Thompson | Display *display; /* the display */ | |
| Mar 29, 2012 at 22:24 | comment | added | Mike Baranczak | See my previous answer: programmers.stackexchange.com/questions/137575/… | |
| Mar 29, 2012 at 21:57 | answer | added | Ando | timeline score: 0 | |
| Mar 29, 2012 at 20:22 | comment | added | Tom W | Useful alternative that demonstrates how to turn a poor comment into a good one: // This is an adjective, not a verb. Provided for consumers that need to retrieve the update location because [x] | |
| Mar 29, 2012 at 20:20 | comment | added | rtperson | @RexKerr - Personally, I feel the way to deal with tautology is self-explanatory, pretty much by definition. Besides, the first rule of tautology club is the first rule of tautology club. | |
| Mar 29, 2012 at 19:27 | answer | added | Caleb | timeline score: 0 | |
| Mar 29, 2012 at 19:00 | answer | added | PearsonArtPhoto | timeline score: 2 | |
| Mar 29, 2012 at 18:59 | answer | added | zzzzBov | timeline score: 14 | |
| Mar 29, 2012 at 18:53 | comment | added | PearsonArtPhoto | I once came across legacy code page=0; //Sets the page to 0. That was my all time favorite example of this;-) | |
| Mar 29, 2012 at 18:37 | comment | added | Kevin McCormick | This is simply an example of poor API Documentation, not code comments. My C# XML formatting for a property like this would look something like "Gets or Sets a Uri that can be used to access this object's update server." | |
| Mar 29, 2012 at 17:53 | comment | added | Robert Harvey | I agree with @CodyGray. This is documentation, specifically API documentation. At a minimum, such documentation should help a new person looking at the method in isolation understand what the method actually does. The example comment you give fails this metric; it should say something more along the lines of "Returns the URI of the update from where the foo is barred", instead of simply restating the obvious. | |
| Mar 29, 2012 at 17:26 | comment | added | Cody Gray | This isn't really a comment, it's actually documentation written in the form of a comment. Different rules apply to API documentation than they do to inline code comments. | |
| Mar 29, 2012 at 15:39 | answer | added | BlueRaja - Danny Pflughoeft | timeline score: 14 | |
| Mar 29, 2012 at 14:31 | comment | added | Rex Kerr | The way to deal with tautology in comments is the way to deal with tautology in comments. (This is a comment.) | |
| Mar 29, 2012 at 13:49 | comment | added | SoylentGray | Instead of just restating the method name with spaces why not describe it better. ie This is the URI that will be queried to find updates for the Foo module. | |
| Mar 29, 2012 at 11:54 | vote | accept | Tamás Szelei | ||
| Mar 29, 2012 at 16:12 | |||||
| Mar 29, 2012 at 11:52 | history | tweeted | twitter.com/#!/StackProgrammer/status/185333579037933569 | ||
| Mar 29, 2012 at 10:55 | comment | added | Lukas Stejskal | return result # returns result | |
| Mar 29, 2012 at 9:31 | comment | added | Tamás Szelei | Oh sorry if I wasn't clear enough, this is just an example that I made up. | |
| Mar 29, 2012 at 9:13 | answer | added | DPD | timeline score: 20 | |
| Mar 29, 2012 at 9:08 | answer | added | SK-logic | timeline score: 54 | |
| Mar 29, 2012 at 8:51 | comment | added | Oded | That specific example looks like a generated code comment (ghostdoc, anyone?). Possibly because of an overly zealous adherence to certain tool warnings (stylecop, anyone?). | |
| Mar 29, 2012 at 8:50 | answer | added | gnat | timeline score: 5 | |
| Mar 29, 2012 at 8:49 | answer | added | Kramii | timeline score: 36 | |
| Mar 29, 2012 at 8:48 | answer | added | James Anderson | timeline score: 0 | |
| Mar 29, 2012 at 8:46 | answer | added | Daniel B | timeline score: 0 | |
| Mar 29, 2012 at 8:45 | answer | added | Andy Hunt | timeline score: 0 | |
| Mar 29, 2012 at 8:40 | answer | added | mjfgates | timeline score: 53 | |
| Mar 29, 2012 at 8:31 | comment | added | Tamás Szelei | It is an Uri, so it is meant to support everything that Uri supports (at least I think it is implicated). | |
| Mar 29, 2012 at 8:29 | comment | added | user1249 | Note: I would consider "The location of the update" to be very vague unless it is crystal clear what "an update" is. Do the system support other kinds of URI's than URL's? | |
| Mar 29, 2012 at 8:26 | history | asked | Tamás Szelei | CC BY-SA 3.0 |