It's more accurate to say: I hate bad comments.
I hate comments
21–30 of 55 posts
Re: I hate comments
#22The comments that he shows are pretty worthless. However, comments are often necessary to explain WHY we are doing something. oven.setTemp(350) // 400 will burn them, 300 they will be mushy fluxCapacitor.setOption(THRESHOLD, 1.21E9) // lower thresholds will prevent return from time travel. Please see http://en.wikipedia.org/wiki/DeLorean_time_machine to review the physics
Both these are fixed by method extraction though.
function setTemperatureToCookPerfectly() {
oven.setTemp(350);
}
function ensureReturnFromTimeTravelPossible() {
fluxCapacitor.setOption(THRESHOLD, 1.21E9)
}
To quote one of the Ruby Rogues, "A comment is a lie waiting to happen."
Re: I hate comments
#23Hopefully no one even moderately unfamiliar with the language the code is written in needs to find out how to fix something that is broken. Citing breaking code by using some global that makes the comment no longer true? Sounds like an abuse of globals or someone not cleaning up the comments, not the comments themselves. So many times I have had to repair code in languages I wasn't quite familiar in or that was simpl…
"This method takes a foo object, applies HTML encoding, and returns an array of the original and the clean code." could be a 3-line unit test that's just as clear to read, but has the side effect of actually being true instead of maybe being true! I would consider that comment just as bad as the ones in my examples, but maybe not quite as obviously so.
> could be a 3-line unit test that's just as clear to read, but has the side effect of actually being true instead of maybe being true!
It also has the side effect of being in a different file to the one you're trying to read.
Re: I hate comments
#24I personally have four reasons for writing comments. If a comment does not fall squarely into one of them, I try to omit it: 1) Why the code is doing what it's doing. What's the motivation? Why is a check necessary? What's the context? 2) High-level overview. 20 lines of code may speak for themselves, but a quick sentence can easily summarize it. I love well-summarized code. "Do X with the Y unless it's Z" is a reall…
3 & 4 are really the only two valid reasons to use comments, in my opinion.
1 & 2 are both better solved with method abstraction. Comments describing what code is doing is always a code-smell to me. If you have 20 lines of code that is non-obvious, think about extracting it to one or more well-named methods.
Re: I hate comments
#25A conversation I once had with a junior developer:
Him: I don't write comments. My code is self-documenting.
Me: Apparently, you have never attempted to read those documents.
Re: I hate comments
#26Comments prove that naming is hard.
If we as developers spent more time on using better names for our objects/methods, we would need less comments.
Re: I hate comments
#27I don't mean to sound patronizing, but if you're implementing counters or banging out numbingly-boilerplate business logic for websites, comments are indeed useless. But when you're reading an obtuse 50-line function that implements some weird algorithm acting on some weird data structure, full of magic-like assumptions, you'd wish no one had deleted comments from it, or... had written them in the first place.
Actually, that's EXACTLY the case I had in mind. Obviously I couldn't put a 50 line function with weird data structures in my blog post, or it would be unreadable. But the point is that comments for that function are bad! They'll rot if you ever change the function or the assumptions at all. Instead, you should break the 50-line function up into smaller functions, and add assertions and test cases for all of those "m…
No offence, but this is incredibly naïve, and it's kind of obviously an opinion that simply stems from working on things that just aren't that conceptually complicated. Some things are actually conceptually complicated, and the why is not at all obvious from the what, no matter how finely you slice the what. Code, inherently, describes what. A sparse set of higher level proper sentence comments describing the purpose of the overall goal for the next part is practically required to make code like this actually comprehensible. For some things, something approaching Literate Programming is best, which is nearly the polar opposite of "comments are bad".
Implementing an advanced data structure is a good example of this. Things that took theoreticians some time to discover, and write/publish in a paper, are not things a random programmer is just going to inherently know from a completely uncommented implementation.
Extrapolating "all comments are bad" from a few examples of pointless comments on mind-numbingly simple and obvious code (which are indeed bad) is silly.
Re: I hate comments
#28Take it up with programming 101 instructors around the world, who beat it into their students' heads that "every line" / "every function" / "every class" etc needs comments, no matter how redundant or bad the comment was, because "good code is commented". No joke, fairly well respected science & engineering university, every line of every program through the first three semesters of a CS program was required to be commented. After a while, slapping in useless and bad comments became habit, required for the assignment to even be considered for grading. It takes a while to break that habit.
Re: I hate comments
#29The comments that he shows are pretty worthless. However, comments are often necessary to explain WHY we are doing something. oven.setTemp(350) // 400 will burn them, 300 they will be mushy fluxCapacitor.setOption(THRESHOLD, 1.21E9) // lower thresholds will prevent return from time travel. Please see http://en.wikipedia.org/wiki/DeLorean_time_machine to review the physics
Both these are fixed by method extraction though. function setTemperatureToCookPerfectly() { oven.setTemp(350); } function ensureReturnFromTimeTravelPossible() { fluxCapacitor.setOption(THRESHOLD, 1.21E9) } Now wherever you see these lines in your code, you know exactly what they are for. To quote one of the Ruby Rogues, "A comment is a lie waiting to happen."
In both those examples information about why the variable needs to be set to that specific value is lost. At some point the variable needs to be set and the more information on why it needs to be set to a particular value the better. You can't pack all the required information into a function name and i would dare say you shouldn't.
Granted I would personally do:
const int perfecttemperature = 350; // 400 will burn them, 300 they will be mushy
.....
oven.setTemp(brownie.perfecttemperature);
Re: I hate comments
#30Hopefully no one even moderately unfamiliar with the language the code is written in needs to find out how to fix something that is broken. Citing breaking code by using some global that makes the comment no longer true? Sounds like an abuse of globals or someone not cleaning up the comments, not the comments themselves. So many times I have had to repair code in languages I wasn't quite familiar in or that was simpl…
I prefer to lean towards overcommenting, and I prefer that developers whose code I will have to work with later do the same.
But as you say, they need to be good comments, and comments that either describe intention or explain something in the language that might be rather obscure can be very useful.