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