[timo614]

I think there may be some confusion.

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).

[electrograv]

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.