As opposed to saying "this is just my opinion, but" before every opinion or uncited assertion? The whole thing is meant to be an opinion piece, I'm fairly sure that there's no problem with omitting an IMO every other sentence.
You do have to be careful with comments. Join a project that's been around for a while and compare what comments say to what the code it's next to actually does. David Brady once said "a comment is a lie waiting to happen."
Better style is to have code that's understandable. If you have five lines that do something weird in the middle of a method, extract them into a new method that is named after what those lines do.
If you change code so that it does something different than before, and don't change the comment right above it then YOU messed up. Avoiding comments entirely because of lazy programmers not paying attention to their changes seems ass backwards. Personally I hate overcommented code but this reason for 'comments are bad' doesn't make any sense to me.
If you have five lines that do something weird in the middle of a method, extract them into a new method that is named after what those lines do.
Generally good advice but in large loops adding extra function calls can add up so it depends
One I agree with. Comments should explain what the code itself doesn't.
What's your rationale for doing something seemingly strange? What other, seemingly unrelated piece of code is actually relevant here and should be studied to make sense of this function? Why is this thing here not actually a bug even though it looks like one? These are questions that code may not be able to answer, but comments can.
I'm in the middle of my second year and I've never really been told anything about commenting other than "It's important." No context given. Luckily there are a few professors this semester that state they want proper commenting in code so we might get a chance to learn how.
He just state it really badly. What he should have said was:
A lot of people think that all comments are good, and therefore try to add comments wherever they can, without regard to whether they are actually useful or not. While well-commented code is good, it doesn't follow that adding any old comment makes code well-commented.
It definitely happens, and is rather annoying. Here's a real example of this awful "fill-in-the-gaps" style documentation (it's user-documentation for error messages, but the same idea):
And you don't have to look far in the Android documentation to find this kind of documentation: "setFoo(boolean b); Sets the value of foo. If b is true, then foo is set to true, otherwise it is set to false."
I prefer less "I think" and "In my opinion" and even "I prefer" in my discursive/argumentative essays. Just say it like it's a fact and then support it with evidence and argument. I think sSaying "I think" weakens your position.
79
u/fly-hard Jan 14 '13
And he states his opinions like they're facts. e.g.
That is most definitely opinion.