51–55 of 55 posts
Earlier quoted context omitted.
Erm no... I'm a C++ developer. I call Java annoying because it is inefficient and has a garbage collector.
And how these particular flaws of Java are relevant to the comments-or-not discussion at hand?
Earlier quoted context omitted.
Wouldn't that function name have to be more like setTemperatureTo350ToCookPerfectly400WillBurn300WillMush to match what the comment is saying? What if later it is determined that the proper temperature should instead be 375 because at 350 they aren't quite cooked enough?
And what would happen in the original? People have a tendency to believe what the comment says, even when the code says something completely different. It's easy to say that you would update both the comment and the value at the same time. But I've seen mismatched comments in code all the time for even a contrived example like this. And then what do you believe? Is the comment right with an incorrect implementation,…
This is a poor example to work off of. You'd probably have something like RECIPE_TEMPERATURE = 350, which you could then tweak to 375 if you needed to...
A more effective example would be
oven.Temp = RECIPE_TEMPERATURE
// we have to wait for the oven to preheat
thread.sleep(time.Minutes * 5)
oven.contents += cookies
Could you make that second line of code into a function preheatOven()? Sure. And your code would be less readable, because you have to break context to go see what the function does... only to find it's one stupid line.
Method names are not comments. They are hints at what the code does. They should not explain why the code is doing it (because the why almost always requires a lot more space than you can fit into a reasonably sized method name).
Hopefully 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.
I 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…
Do you leave unused functions in your code when you refactor? No. So refactor your comments, or delete them if they are no longer applicable, when you refactor your code.
I have been saved many times by comments in my own code, because you know I work on a lot of stuff, sometimes coming back to it after years and I hope I have developed as a coder and so my mindset is now different and a lot of the time I do wonder WTF was I doing here!
This is the opposite of your post http://tech.collectedit.com/post/2012/11/12/Comment-your-dam... which I tend to agree with a lot more.
Your code tells me what you did. Your comments tell me what you intended. Help me out. Help your future self out!
Earlier quoted context omitted.
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.
his 1st point was not about commenting what code does but why it is done the way it is. I don't see how you can extract all the required information (including web links or rational) explain the rational behind a implementation into a function name. // unroll loop for 50% speed increase. Optimal offset 4 // 3: 25% // 4: 50% // 5: 40% for(i=0;i How could you extract that into a function name? 2 is definitely more an o…
I'm not talking about your opinion on point 2 here specifically, but your comment reminded me of a discussion I had with someone about comments... well, they were arguing (like the OP) that you should not use comments in your code but they would gladly use XML comments for the same reasons you have stated. So they would go to the lengths of helping out external developers with comments but not their own internal developers. Seemed very strange to me!