4 ms·

As of git HEAD at the time of this comment (5edce74): 1499 lines of Ruby code. 19 lines of comments. Nope, nope, nope. I would never touch this library. Goo

As of git HEAD at the time of this comment (5edce74): 1499 lines of Ruby code. 19 lines of comments. Nope, nope, nope. I would never touch this library. Good amount of tests, but the moment this library doesn't work as expected and you need to jump into the code, you're completely screwed. Not usable.

burke 14y ago
What part of the code isn't self-explanatory that a comment would be able to band-aid? It's all very clean. Comments for comments' sake are much worse than no comments at all.
mweibel 14y ago
didn't look at the code but if it's good code, why would you need more comments? Good code explains itself.
- nirvdrum 14y ago
  Do you have an example of good code that explains rationale or "why" without comments? I rarely come across code and can't figure out what it's doing, but I routinely come across code and can't figure out why it's doing something. And I haven't found a good way to deal with that outside of comments or some external documentation. I'd love to see examples of code that's able to overcome this.
  - mweibel 14y ago
    Well done code has good variables, good method/function naming and small methods/functions. If you have those 3 parts, you won't need any comments because it's self explanatory. Comments often tend to explain the same thing as the code exactly does and what you see w/o looking at the comment. Also, they tend to be forgotten - if someone changes the code, he/she often doesn't change the comment. As a result, you'll have an outdated comment which can confuse you. I recommend "Clean Code"[1] for more info on this subject. Beside other chapters, there's a chapter about what's a good and what's a bad comment. [1]: http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882/ref=sr_1_1?ie=UTF8&qid=1341586548&sr=8-1&keywords=clean+code http://www.amazon.com/Clean-Code-Handbook-Software-Craftsman...
    - nirvdrum 14y ago
      I've never come across self-documenting code that can explain "why," which is what I was seeking. The closest thing I've ever come across was a PhD student working on a system called Seurat, but even that was really metadata attached to the code (something akin to an SCM). I agree clean code can help with the "what" or the "how", but that's almost never the problem to begin with. In any event, I was looking for solid examples, not a general discussion on whether comments are good or bad. We clearly are not going to agree on that point so we'll save the Internet another pointless argument :-)
      - mweibel 14y ago
        Ok I might have misunderstood you ;) Well I'm not saying comments are generally bad. But I think a lot of comments can be replaced by better code :) Solid examples I can't really show you atm (I'm not yet there where I'd say from myself that I write the cleanest code ever) ;)
guns 14y ago
You're screwed because you won't possibly be able to follow a well composed, well tested library with an extremely shallow class hierarchy and short, clear method definitions without the aid of comments? I don't think you're giving yourself enough credit. A quick glance at the source shows that the size of the program is a result of implementing the many methods one expects from collection classes in Ruby, not because the code is especially byzantine. In fact, I haven't seen a single instance of class inheritance; the author seems to have chosen to solely use a few well defined modules instead.
exDM69 14y ago
1.5 kloc of code is only a few hours to grok. Get over it.

burke 14y ago

What part of the code isn't self-explanatory that a comment would be able to band-aid? It's all very clean. Comments for comments' sake are much worse than no comments at all.

mweibel 14y ago

didn't look at the code but if it's good code, why would you need more comments? Good code explains itself.

nirvdrum 14y ago
Do you have an example of good code that explains rationale or "why" without comments? I rarely come across code and can't figure out what it's doing, but I routinely come across code and can't figure out why it's doing something. And I haven't found a good way to deal with that outside of comments or some external documentation. I'd love to see examples of code that's able to overcome this.
- mweibel 14y ago
  Well done code has good variables, good method/function naming and small methods/functions. If you have those 3 parts, you won't need any comments because it's self explanatory. Comments often tend to explain the same thing as the code exactly does and what you see w/o looking at the comment. Also, they tend to be forgotten - if someone changes the code, he/she often doesn't change the comment. As a result, you'll have an outdated comment which can confuse you. I recommend "Clean Code"[1] for more info on this subject. Beside other chapters, there's a chapter about what's a good and what's a bad comment. [1]: http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882/ref=sr_1_1?ie=UTF8&qid=1341586548&sr=8-1&keywords=clean+code http://www.amazon.com/Clean-Code-Handbook-Software-Craftsman...
  - nirvdrum 14y ago
    I've never come across self-documenting code that can explain "why," which is what I was seeking. The closest thing I've ever come across was a PhD student working on a system called Seurat, but even that was really metadata attached to the code (something akin to an SCM). I agree clean code can help with the "what" or the "how", but that's almost never the problem to begin with. In any event, I was looking for solid examples, not a general discussion on whether comments are good or bad. We clearly are not going to agree on that point so we'll save the Internet another pointless argument :-)
    - mweibel 14y ago
      Ok I might have misunderstood you ;) Well I'm not saying comments are generally bad. But I think a lot of comments can be replaced by better code :) Solid examples I can't really show you atm (I'm not yet there where I'd say from myself that I write the cleanest code ever) ;)

guns 14y ago

You're screwed because you won't possibly be able to follow a well composed, well tested library with an extremely shallow class hierarchy and short, clear method definitions without the aid of comments? I don't think you're giving yourself enough credit. A quick glance at the source shows that the size of the program is a result of implementing the many methods one expects from collection classes in Ruby, not because the code is especially byzantine. In fact, I haven't seen a single instance of class inheritance; the author seems to have chosen to solely use a few well defined modules instead.

exDM69 14y ago

1.5 kloc of code is only a few hours to grok. Get over it.