I think comments should be more to explain the why and not the what necessarily. Even in the example x+=n, the what part is simple. you are adding n to x. But why are we doing it there could be important to comment in the context. May be this addition changes the variable to trigger another action etc ?
I'd say build your code such that you don't need to comment but comment wherever there is some unclear reason for why something is done.
Instead of x+= n;
running_total += total;
But comments are helpful for understanding the reasoning behind why something was done.
For example:
$.resize.delay = 16;
Was placed in one file of some code I collaborate on with the comment "// this is probably a horrible idea"
I had to ask the developer what exactly the code does (yeah I could have looked it up but since he said it was a horrible idea I wanted to know why). Turns out it just configures the jquery resize event to fire at about 60 frames per second.
Having a comment like:
// Configures jquery resize to fire the resize event approx 60 frames per second
Would have made the code a bit easier to understand.
> Having a comment like: '// Configures jquery resize to fire the resize event approx 60 frames per second' Would have made the code a bit easier to understand.
I'd argue that the following line is a better solution in every way than adding a comment as you suggest:
setResizeEventFireRate(60); //just pseudocode of course
Self-commenting code is always better: less duplication, less maintenance, greater refactoring agility, and most of all, it encourages you to design a cleaner system in the first place.
Granted, in real-world scenarios, there will always be many cases where you are forced to add comments, sometimes extensively (hand-optimized code, inherently complex systems, etc).If anything though, this only confirms how important it is to aim for self-documenting code.
Real-world production code is rarely a pretty thing, and the fact that you have to start adding comments everywhere is a reflection of this. You'd be surprised how clean and elegant code becomes when your only goal is to make it as self-descriptive as possible.
Not surprised -- definitely agree that the code involved could be improved.
That said there is a bit of a code smell to what you're describing; having separate functions just to set the resize event time is a bit much.
What I think would be better is to set a constant to the resize frame rate and then remove magic numbers so that people viewing the code would understand how it works implicitly without the comment like you're describing. That or improving the library such that it's more clear what's exactly happening.
The "//just pseudocode of course" meant that that wasn't actually how you'd do it. Instead, you'd come up with an overall better design in how you handle resizing pages. If anything this proves the point that self-documenting code forces you to re-think your design often when something is fishy to begin with. In this case, setting "$.resize.delay = 16;" probably is an effect of deeper design issues. Not being able to fix it by just moving it into a function simply means that striving for self-documenting code forces you to fix the issues rather than patch them with half-hearted (or worse - a highly detailed) comment.
If there was ever 'code smell', it's when you see "x = y; // verbose way of saying sets x to y". And this is exactly your example - a verbose description of "$.resize.delay = 16;" If renaming variables and functions in this case doesn't make you feel better, I don't see why a comment would.
But yes... of course comments are important and needed in some cases, which I admit. However when they do, as other posters here have mentioned, it's usually annotating why, not how/what. I can't think of many reasons why it's not a bad sign if you find yourself explaining how something works - the only one that comes to mind is with hand-optimized code.
The code in question is a configuration option for a third-party jquery plugin. There may be better plugins which expose their configuration options differently but I personally think that the benefits of using the library itself outweigh building something entirely from scratch for a more purist interaction. I've worked with some gross libraries before and I think that the benefit of using them outweighs a few comments for obscure settings.
The third party code in question isn't terrible as you can assume it's the resize delay from its name. I think what made it terrible was the fact that since a magic number was used (16) it wasn't as apparent for a reasonable developer to grasp without questioning it. Yes, some people will know that 16 milliseconds equates to around 60 frames per second but I don't think it's reasonable to assume everyone who looks at it will. It was a bad example on my part, however, as with a constant as opposed to a magic number you don't need the comment at all.
The code smell I mentioned was wrapping a third party configuration in a function as a way to limit commenting. I think commented configuration options make it easier for other developer to grasp why something is configured that way -- especially for code that will be minified.
I don't think I explained well enough that the code in question was from a third party interaction, however, so could see how we may be on different wavelengths. I'm also by no means a purist when it comes to comments though so I'm sure we may have opposing views (although I agree with the general idea as you mentioned to annotate why not how/what).
Be it as it may, magic number or not, that line should not need a comment. My principle above still holds: needing comments tends to hint that your design could be better and/or your code could be cleaner.
Maybe your library is flawed. Maybe JS is fundamentally flawed. I'm not making any comments one way or another about what's flawed in this picture or how to fix it, just that seeing this comment indicates room for improvement.
Imagine the ideal design/architecture for a given application on all levels. Does it involve the users of this code or API explaining everything in lengthy comments? Or does it involve a clean, beautiful, and elegant set of interactions that is both transparent and intuitive as to what is going on? The latter, I argue, needs no comments. The former, I argue, is indicative of design flaws or inadequate function names.
So why do we see necessary comments in real life, then? Because real life system designs are rarely ideal. I still like to try to get as close as I can, though.
The thing is, having a comment in a tricky bit of code, and knowing that the comment may be confusing because some jackass (maybe myself six months ago ?) changed the code but missed the comment is IMHO still better than having no information whatsoever.
