3 ms·

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 ro

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

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