5 ms·

cleaner code is not a good replacement for cleaner comments either though.

• wolco 9y ago
  But cleaner code can remove the need for a comment.
• wglb 9y ago
  In "Refactoring", Martin Fowler says that "comments are bugs".
  • anarazel 9y ago
    The amount of damage Martin Fowler has done with his writing...
    • wglb 9y ago
      What in particular has caused damage?
      • khedoros1 9y ago
        Well, good code obviates the need for most comments. A comment shouldn't cover up a bug of clarity in a piece of code, in almost any case imaginable (basically, if it isn't a Fast InvSqrt() level of utility, the dev ought to reconsider the "cleverness" of the code). And anyhow, the implementation details of the code are liable to change; the comment becomes outdated, and there's a good chance that it won't be updated. What about a comment that notes what part of a spec some code implements (i.e. something outside the actual behavior of the code)? A comment that answers "why" can be helpful, and can sometimes be worth the high cost that an unchecked, unexecuted part of the program inherently carries. If Fowler's claiming that all comments are bugs, I'd call that damaging.
• ska 9y ago
  When you need comments, they should be clear. But when you can make the code clear enough to need no commenting, you should do that instead.
  • hermitdev 9y ago
    Comments need to explain why they are doing something, not what the code is doing. I can tell what the code is doing by reading the source. Otherwise, I agree. The code should be clear enough that no comments are needed.
• dalore 9y ago
  The code is the comment if it's written well.
  • ridiculous_fish 9y ago
    Some clang code: // ISO/IEC TR 18037 S5.3 (amending C99 6.7.3): "A function type shall not be // qualified by an address-space qualifier." if (Type->isFunctionType()) { S.Diag(Attr.getLoc(), diag::err_attribute_address_function_type); Attr.setInvalid(); return; } The comment justifies the code in a way that the code itself never could.
    • mikekchar 9y ago
      A unit test could document that equally well (although the pointer to the spec would still be useful). Whether or not it would fit your style of programming is another matter, of course.
      • deleted 9y ago
        [deleted]
      • VMG 9y ago
        A unit test would almost certainly explain the behavior in a completely separate place. That's not documentation.
    • dalore 9y ago
      if (isTypeFunction) { showErrAttrDialog(Attr); setInvalid(Attr); }
      • khedoros1 9y ago
        Maybe I'm missing something. The code that you've written doesn't look any clearer to me than the code from the compiler itself, and without the comment, there's no "why" for the behavior. Later, if a bug is filed saying that the compiler isn't compliant with the requirements of "ISO/IEC TR 18037 S5.3", how can you be sure to find the code where the behavior is implemented?