Timeline for Overused or abused programming techniques
Current License: CC BY-SA 2.5
26 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| Jan 19, 2011 at 20:29 | vote | accept | Anto | ||
| Jan 17, 2011 at 18:59 | comment | added | Scott Whitlock | @Mike Woodhouse - yeah, but I can't edit it now... | |
| Jan 16, 2011 at 22:01 | comment | added | user8709 | @user9094 - what if you don't fully understand the comment? By changing it, you could lose information that someone else might benefit from. As you're busy at the moment, you may think, and you don't want to interrupt your current flow, you'll leave that for a bit and get back to it later... but later may be much later than you intended. | |
| Jan 16, 2011 at 8:41 | history | made wiki | Post Made Community Wiki | ||
| Jan 14, 2011 at 13:21 | comment | added | DisgruntledGoat | When I was at Uni they used auto-marking a lot (mainly in the first year), including points for "commenting your code". But it only checked for the existence of a comment. We always used to put things like // This comment doesn't explain any of my simple code but has be here to get the marks | |
| Jan 13, 2011 at 17:48 | comment | added | JBRWilkinson | If you have a source code indexing system, like lxr or grok, try searching for some rude or swear words. Are they in the code or in the comments? While at Microsoft, we found an awesome programmer that wrote lots of comments but unfortunately just did not know the correct spelling of couldn't. | |
| Jan 12, 2011 at 20:15 | comment | added | Robert Harvey | @Steve314: I am in favor of writing code that is self-describing. I am also in favor of adding comments when it is useful to do so. I like syrup on my waffles, but not if it overflows the plate. | |
| Jan 12, 2011 at 13:02 | comment | added | wildpeaks | I don't understand people who don't update their comments when they modify a function: you wouldn't leave the old version of the code when you modify a function, so why stop halfway ? This kind of lazyness makes me want to shake the stupid of the people who do it. | |
| Jan 12, 2011 at 12:00 | comment | added | Neil | If you have to explain the "how" in your code, you're implying that it's not clear by looking at the code what it does. REWRITE IT! Comments should only explain why not how. | |
| Jan 12, 2011 at 9:19 | comment | added | Mike Woodhouse | @Bill - for the example you provide (regex sample ins/outs) would it not be even better to provide the documentation in executable unit tests? If you really need to spoon-feed the reader, the comment might then simply direct them to those tests. | |
| Jan 12, 2011 at 9:17 | comment | added | Mike Woodhouse | @Scott - the copy of Clean Code on my desk was written by Robert C. "Uncle Bob" Martin, although I'm sure Fowler (I assume you meant Martin?) would be pretty much in agreement. ;-) | |
| Jan 12, 2011 at 3:17 | comment | added | user8709 | @Robert - I aim to write self-documenting code. I also write a lot of Doxygen annotations, a few other comments, and a fair bit of separate documentation. That's not hypocrisy, but I do think some anti-self-documenting-code claims recently are misrepresenting what it means. Obviously you can't document everything by e.g. choosing clear identifier names, but that doesn't mean there's no value in doing so, and by avoiding the need for many comments that way you get the opportunity to add comments for other things without creating excessive clutter. | |
| Jan 12, 2011 at 3:11 | comment | added | Robert Harvey | Self-documenting code...Programmer religion flavor of the week. | |
| Jan 11, 2011 at 22:15 | comment | added | Woot4Moo | @Scott if you see my caveat I address your issue. | |
| Jan 11, 2011 at 22:14 | history | edited | Dan McGrath | CC BY-SA 2.5 | Missing word... |
| Jan 11, 2011 at 22:12 | comment | added | Bobby Tables | @Bill: Yeah, that's a good example of what SHOULD be commented. :) | |
| Jan 11, 2011 at 22:09 | comment | added | Bill | @Guzica I agree generic stuff should not be commented. But just as there is good coding and bad coding, there is also good commenting and bad commenting. Complex systems require commenting. For example, I work in the ISP world, where we often need to use a lot of complex regex's against a bazillion network devices. Putting in an example of the output being regexe'd against improves understanding of the code. | |
| Jan 11, 2011 at 22:02 | comment | added | Dan McGrath | That's not the point I was making though. I totally agree 'why' is important, that is the second part I was attempting to imply with 'cannot be adequately self-documented'. My issue is with people who write comments with that have the same benefit as a turnip ASCII art picture in the code. I don't think anyone should hide behind 'self-documenting' code, I just believe that is how it should be written full stop, no excuse. Whatever is left to be commented such as why & business rules it is implemented are all I should read as comments. Not paraphrasing the sytnax I can already read... | |
| Jan 11, 2011 at 21:56 | comment | added | Bobby Tables | @Bill: My take on it is that you shouldn't need to document generic logic and control structures, even if they are relatively complex. Basically, anything that a good developer who knows the language should be able to work out by analysing the code shouldn't need to be commented. eg. A set of nested for loops with some breaks inside them, etc. But what SHOULD be commented is the application-specific reasoning of why the code makes those decisions: eg. "If a new programmer starts at the company tomorrow and looks at the code, will what it does make sense without the comment hints?" | |
| Jan 11, 2011 at 21:47 | comment | added | Bill | The mantra of self-documenting code is overused. Programmers are usually not the users of the program they create, as such they often write code about processes they only have a passing familiarity with. Taking the time to explain "why" something is done, rather than just "how" is invaluable for later programmers. Hiding behind "self-documenting" code is often an excuse to be lazy. | |
| Jan 11, 2011 at 21:45 | comment | added | Craige | @Guzica - Eeeeeewwwwwwwwww. | |
| Jan 11, 2011 at 21:38 | comment | added | Bobby Tables | +1. I've actually seen the following in real world code: "loopVar++; // increment loopVar". AAAAAAAAAAAAARRRRRGH! | |
| Jan 11, 2011 at 21:37 | comment | added | Shog9 | Teaching them to replace comments with code would be a good start... | |
| Jan 11, 2011 at 21:35 | comment | added | Scott Whitlock | @Woot4Moo: if you read Clean Code, Fowler clearly states that out-of-date documentation is worse than no documentation, and that all comments have a tendency to become stale and to migrate away from the code they document. That whole book is all about how to write self-documenting code. | |
| Jan 11, 2011 at 21:04 | comment | added | Woot4Moo | Self-documenting code isn't . Also professors do this to teach students to conceptualize the problem and how to approach it. Additionally I have never seen anyone complain about too much documentation. Caveat being the documentation is correct. | |
| Jan 11, 2011 at 20:57 | history | answered | Dan McGrath | CC BY-SA 2.5 |