Not that I don't agree, sometimes unnecessary comments kind of make it a bit complicated to understand what's going on. BUT, an important point to mention is that coders write code in different styles and manners, there is no right and wrong when it comes to comments. Sometimes just seeing that comments exist (even if some lines are pointing the obvious) makes a difference to the inexperienced or to the new-comers. Not to mention that "obvious" here depends heavily on the experience of the developer with language, framework, or whatever they're using. I guess the person writing the code should at least get to write comments the way the like. You're a programmer, reading a couple of extra comments won't ruin your day, just skip it if it's obvious.
Stop commenting your code just to say you did
41–50 of 76 posts
Re: Stop commenting your code just to say you did
#42Don't listen to this guy. Copious comments are great. 1. They act as a easier-to-skim narrative of the code. You can often get an outline of a well-commented component by reading the comments alone, rather than by picking apart a language designed for machine consumption. Syntax highlighting makes this especially easy. 2. They're helpful for other programmers who may not be as comfortable in the language as you are.…
Don't code for machine consumption, code for programmer consumption. Code is read 5x more than written, etc. Use function/method/class names that are readable like an outline.
Code comments are a poor teaching tool. Use a coding style guide/standard, pair programming, training, or a book to teach basic language idioms.
I don't buy the "searching argument". Ctrl+F for "account" will match a method named "lookupAccount" just as well as a comment that says "//lookup account". If you use a somewhat consistent naming scheme, it will probably be easier to search for something - try finding more than 2-3 words in a row in prose.
Putting so much perceived value and trust into code comments is like trusting "Architecture Design.docx" instead of looking at the actual running code.
Re: Stop commenting your code just to say you did
#43God forbid someone gets their thoughts together with comments outlining what a function is going to do and then fills in the code... Or, while deep in thought, someone taps out a bit of redundant commentary on a line or two of their code... Or someone needs a bit of natural language to provide an anchor in their code. The important thing here, I think we can all agree, is that we are smarter than that person.
// don't use hardware acceleration canvas.enableHardwareAcceleration(true); Which is true? The comment is lie. Is this a bug? Was this changed for some reason? Should I remove the comment? Should I toggle the boolean? Why weren't we supposed to use HW acceleration? Why are we using it now? What changed? What value did the comment have in the first place?
Almost every time I've done this, that pattern means "I really shouldn't be doing it this way, but we'll do it this way for now because getting it done is more important. Improve it if emergent bugs or profiler results ever indicate it's worth messing with again, but I'll probably get back to it never."
It's not a TODO or a BUG, but it's helpful to make note of for future code review or reuse.
Re: Stop commenting your code just to say you did
#44I'm beginning to believe that if code is simply a machine-interpretable codification of human expertise, then we should be able to express precisely what the code should be doing using written language as well.
I've been turning this over in my head to figure out how it should look in practice, but I'm wholeheartedly believing the following statement is true:
"All code should be composed in two languages: first in whatever programming language the task requires, and second in whatever language the programmer speaks natively."
Re: Stop commenting your code just to say you did
#45Earlier quoted context omitted.
// don't use hardware acceleration canvas.enableHardwareAcceleration(true); Which is true? The comment is lie. Is this a bug? Was this changed for some reason? Should I remove the comment? Should I toggle the boolean? Why weren't we supposed to use HW acceleration? Why are we using it now? What changed? What value did the comment have in the first place?
Almost every time I've done this, that pattern means "I really shouldn't be doing it this way, but we'll do it this way for now because getting it done is more important. Improve it if emergent bugs or profiler results ever indicate it's worth messing with again, but I'll probably get back to it never." It's not a TODO or a BUG, but it's helpful to make note of for future code review or reuse.
Do you always do project management/backlog grooming inside your source code? ;-)
Re: Stop commenting your code just to say you did
#46Earlier quoted context omitted.
// don't use hardware acceleration canvas.enableHardwareAcceleration(true); Which is true? The comment is lie. Is this a bug? Was this changed for some reason? Should I remove the comment? Should I toggle the boolean? Why weren't we supposed to use HW acceleration? Why are we using it now? What changed? What value did the comment have in the first place?
It's a pain but check the git history.
It's not a pain. Source control history is the ultimate commentary. But the same ideas apply to commit messages as to source comments - if they say what instead of why, they don't help much.
Re: Stop commenting your code just to say you did
#47God forbid someone gets their thoughts together with comments outlining what a function is going to do and then fills in the code... Or, while deep in thought, someone taps out a bit of redundant commentary on a line or two of their code... Or someone needs a bit of natural language to provide an anchor in their code. The important thing here, I think we can all agree, is that we are smarter than that person.
// don't use hardware acceleration canvas.enableHardwareAcceleration(true); Which is true? The comment is lie. Is this a bug? Was this changed for some reason? Should I remove the comment? Should I toggle the boolean? Why weren't we supposed to use HW acceleration? Why are we using it now? What changed? What value did the comment have in the first place?
>What value did the comment have in the first place?
That comment is the only indicator that something may be wrong. Your next steps are the same as with any suspected bug, find out what the code is doing (seems obvious here) and then find out if that's what it should be doing.
That comment, however, is a good example of a bad comment. In this particular scenario, it's very obvious what the code is doing, so the comment should describe why the code is doing what it's doing. Much like should do:
//set volume to 5
x = 5;
//set x to 5
x = 5;Re: Stop commenting your code just to say you did
#48One of my guiding principles for code comments has always been "say why not what". If I can't figure out that what on my own then something is probably very wrong with the code. What I want to know is why you used a for() instead of a while() to iterate over an array or things like that. Comments that explain what you're doing I find to be cruft. I don't necessarily hate on them but I do find them unnecessary and unhelpful.
Re: Stop commenting your code just to say you did
#49God forbid someone gets their thoughts together with comments outlining what a function is going to do and then fills in the code... Or, while deep in thought, someone taps out a bit of redundant commentary on a line or two of their code... Or someone needs a bit of natural language to provide an anchor in their code. The important thing here, I think we can all agree, is that we are smarter than that person.
// don't use hardware acceleration canvas.enableHardwareAcceleration(true); Which is true? The comment is lie. Is this a bug? Was this changed for some reason? Should I remove the comment? Should I toggle the boolean? Why weren't we supposed to use HW acceleration? Why are we using it now? What changed? What value did the comment have in the first place?
// Hardware acceleration should be switched off.
// Originally we'd planned to use hardware acceleration but later
// on in the project's life cycle we were told we needed to support older
// versions of Foo: X and Y. This caused some bugs documented [here](#123) and [here](#234)
// due to incomplete support of feature Z and the way that [internMethod()](#internMethod) is currently implemented.
// @TODO: It would be better if we could switch it on or off depending on the device.
canvas.enableHardwareAcceleration(true);
They should describe why and the high-level how, while code should describe what and the the low-level how.
That's just my opinion. This is the kind of comment I write. From time to time it becomes incorrect when a project's moving fast, but I write enough that it's very easy to validate that the use cases and code I'm talking about are real. You're meant to delete the comment immediately if it's incorrect: you can choose to help the next person understand the code or not, that's not up to me.
I think something that's very important is trying to show where a line of code or method fits in the greater scheme of the architecture of the code by linking it towards the methods that are interrelated in important ways.
Edit: You might notice I've left the comment not matching the code. This is a fact of life: somebody will change the code without updating the comment. However, because of the comment you now have a great way of sanity checking this change without having to find the original coder or test it all. Basically: it tells you what you couldn't quickly know looking at uncommented code.
Re: Stop commenting your code just to say you did
#50Earlier quoted context omitted.
Almost every time I've done this, that pattern means "I really shouldn't be doing it this way, but we'll do it this way for now because getting it done is more important. Improve it if emergent bugs or profiler results ever indicate it's worth messing with again, but I'll probably get back to it never." It's not a TODO or a BUG, but it's helpful to make note of for future code review or reuse.
Do you always do project management/backlog grooming inside your source code? ;-)
I'm of the philosophy that code should be readable, reasonably self-documenting, and remind you of relevant external material - whether that be your state of mind at the time, or reference material you drew on, or whatever.
Not everything needs an open issue, but the knowledge should be recorded somewhere. I know for a fact I won't remember it in six months, and likely not in a week either.
(I also write a large amount of utility code that's below the "project" scale and will probably never see a PM tool, but which is nonetheless part of a heavy reuse ecosystem.)