3 ms·
The problem with comments is people misuse them. Comments should explain decisions, not code. Why are you doing this? Not how, I can see how from your code if i
by Swizec 14y ago
The problem with comments is people misuse them. Comments should explain decisions, not code. Why are you doing this? Not how, I can see how from your code if it isn't crappy. If I can't see how from the code, you should improve the code.
And by "you" I mean whomever wrote the code I'm looking at. Usually my past self.
I think what I'm saying is that the problem with comments is semantics, not UX.
- maigret 14y agoIndeed. And one of the reason for the why, beside just understanding the context and getting a more complete picture, is to allow further developers to add code at the same place because it was meant like that in the original code. Great comments helps to know if a new module should be written, or if the addition fits nicely in the existing picture.
- mmahemoff 14y agoThis is a problem with education (a lot of introductory textbooks and teachers miss the point). To be fair, people learning to code need different comments from more experienced developers (http://steve-yegge.blogspot.co.uk/2008/02/portrait-of-n00b.html http://steve-yegge.blogspot.co.uk/2008/02/portrait-of-n00b.h...) Another cause is paranoid architects. Lint-testing to ensure even one-line getters and setters are commented. Come on! But it happens in real life.
- qznc 14y agoIn my opinion the why belongs into the commit message not into a comment. Whys are usually highly context-dependent and you should not include all the context into the comment ("in 2004 we benchmarked A,B and C on such and such a machine and B was fastest"). If it is not context-dependent the solution is obvious and needs no comment.
- ryanbrunner 14y agoAssuming that the solution is always obvious from the code is naive and dangerous. You should always strive to make code speak for itself, but there's occasionally cases that require you to do something unintuitive for some reason or another, and comments serve as a useful warning sign or explanation for future programmers (something that a commit message is uniquely unsuited for) Going through a few files on one of my codebases, here's some of the useful comments that I can find from a quick skim: - Explaining why a dummy argument existed on a method (a third-party library required it) - Explaining why we need to set a weird inheritance column on an ActiveRecord model (we're using 'type' as an actual column) - Calling out some technical debt that could be fixed by someone at some point. All of these are really about calling out why the solution is not obvious.
- pm215 14y agoMy rule of thumb is that you can't expect people reading the code to go diving into the revision control history. So if a reader of the code needs the information, it goes in a comment. Commit messages justify the change; comments justify the code as it stands. I think these are different kinds of 'why' (though they can certainly often overlap a lot).
- bunderbunder 14y agoI re-taught myself this just the other day. I had written some code that was hard to understand. So I wrote a comment to explain how it was supposed to work. I come back a couple months later, and guess what? The comment might have made complete sense to the guy who just wrote the code, and therefore already understood how it worked. But to someone who didn't it was completely opaque, and therefore only served to make me more irritated the person who wrote it. (i.e., me a couple months ago.) So that's why I don't like that style of comments. If the code alone doesn't make sense, then 90% of the time the comments that try to explain it don't make any sense either. Maybe the only situation where this kind of comment is acceptable is if you have to use some hairy dynamic programming algorithm or something like that, in which case the comment should just be the name of the algorithm and a URL for a page that explains it.