4 ms·
Although I enjoy jashkenas' Javascript documentation a great deal and find it extremely helpful, I'm having a hard time getting excited by the resurrection of i
by bguthrie 16y ago
Although I enjoy jashkenas' Javascript documentation a great deal and find it extremely helpful, I'm having a hard time getting excited by the resurrection of interest in literate programming. I enjoy and appreciate the notion that code should be designed by humans to read, but I'm reminded of (and agree with) Bob Martin's admonition in Clean Code that energy spent polishing one's code commentary is better spent improving the readability and flow of the code itself.
Also, comments that come across elegant and attractive when rendered in HTML look teeth-gratingly gratuitous when viewed in the context of the original code. For example,
// Attach all inheritable methods to the SomeObject prototype.
_.extend(MyLib.SomeObject.prototype, MyLib.SomeMixin.prototype, { ... })
Yes, that's an accurate description of what it does. But if you can read Javascript, you should know that; in code, it's visual clutter, and worse, it adds overhead to maintain it when you move or update your code.
- jashkenas 16y agoRedundant comments are as annoying as repeating yourself in writing. Redundant comments are as annoying as repeating yourself in writing (and I'm certainly as guilty of it as anyone). But the real point of the comments is to explain the "why", just as the code explains the "how". In your example above, to explain the reason that you've chosen to mix in the modules you're mixing in...
- bguthrie 16y agoI was trying to be subtle about it, but the example I used was drawn from a fairly well-known (albeit, I should add, well-written) JS library. My point is that this style of documentation encourages that behavior, perhaps paradoxically because it's so attractive and big hunks of whitespace tend to stand out.