4 ms·

I can't agree with you emphatically enough about this. Cargo cult commenting is one of the easiest ways to damage the readability of a codebase. Comments shoul

by h2s 14y ago

I can't agree with you emphatically enough about this. Cargo cult commenting is one of the easiest ways to damage the readability of a codebase. Comments should be an edge-case solution for explaining unusual quirks, not the go-to approach for explaining the entire codebase. Using comments to explain what the code is up to is like using exceptions for flow of control. A large proportion of the comments I see should actually be function or method names for a more well factored version of the block of code that follows.

randomdrake 14y ago
I agree that comments should not be the "go-to approach for explaining the entire codebase." I hope you didn't think I was insinuating that in my comment. I was only trying to illustrate that in the absence of clear code, which many developers are guilty of sometimes, comments can be very helpful.
- h2s 14y ago
  Nah I didn't think that at all, it was clear from the way you said "minimal commenting". I just have an axe to grind when it comes to comments of the form // assign the integer value 10 to the variable x x = 10
  - miahi 14y ago
    What's really annoying is that most of the time you see this kind of comment there is no explanation why 10 was chosen.
    - dhimes 14y ago
      And that's what comments really need to do: tell 'why.'
      - Pyrodogg 14y ago
        http://xkcd.com/221/ http://xkcd.com/221/
    - MetallicCloud 14y ago
      That's why you should use constants. Still self documenting without the need for comments (usually).
      - adamzegelin 14y ago
        const TEN = 12;
        tehwalrus 14y ago
        #define true false
    - fudged71 14y ago
      In our embedded systems class we were required to define all of our constants, just to add another level of description to operations. It definitely helped to navigate spaghetti code.
  - mikeash 14y ago
    At least it's better than: // set the variable x to 10 x = 12;
    - sixothree 14y ago
      sFile = "filename.xml"; then later sFile = File.ReadAllText("filename.xml");
    - zvrba 14y ago
      I think you've forgotten a leading zero ;)
- bunderbunder 14y ago
  Sadly, I fear that comments won't help in that situation. They could, except that the solution depends critically on the developer realizing they're writing garbled code during the time they're writing it. I don't know about anyone else, but my code's never garbled when I write it. It only becomes garbled by magic, and only when I don't look at it for a few weeks. Or, strangely enough, the moment someone else looks at it. Still haven't figured out a reliable enough garble detection mechanism that my employer's willing to pay for.
mjbellantoni 14y ago
"A large proportion of the comments I see should actually be function or method names for a more well factored version of the block of code that follows." I share the same experience.
RegEx 14y ago
This point gets brought up a lot, but I'm not going to complain at all. In fact, just 5-6 months ago I used to be one of those programmers who would do # gets the xml def get_xml(): It took comments like this to help me realize just how silly the whole thing was. Now I write as much self-documenting code as I can, but comment as needed.
- bonch 14y ago
  It's all subjective, but that comment could be expanded to, for example, explain where the XML is assumed to be coming from or what kind of XML is expected. If the code makes no assumptions about those things, that is also something to write a comment about.
- Funnnny 14y ago
  Sure. Comment should be "why I did this", and code should be "how I did this", some people just write in "what did I do" and walk away thought they have comment Code took from a project I'm working with: #End of package
  - StavrosK 14y ago
    I generally become aware that I should leave a comment whenever I write something that is less than trivial (but exactly less than trivial) to write/understand. Longish list comprehension? Summarize what it does. Nested function calls? Summarize why. Etc.
  - chii 14y ago
    > Comment should be "why I did this", and code should be "how I did this" the problem starts when the 'why' doesn't match the 'how'...which one is "correct"?
ozgung 14y ago
This may be a valid argument for modern languages like Ruby or Python. For 90s' coding standards however comments are even MORE important than the code itself. For Assembly and C programming and for low level graphics and physics algorithms proper naming of variables and functions are never enough for readable code.

by h2s 14y ago

randomdrake 14y ago

I agree that comments should not be the "go-to approach for explaining the entire codebase." I hope you didn't think I was insinuating that in my comment. I was only trying to illustrate that in the absence of clear code, which many developers are guilty of sometimes, comments can be very helpful.

h2s 14y ago
Nah I didn't think that at all, it was clear from the way you said "minimal commenting". I just have an axe to grind when it comes to comments of the form // assign the integer value 10 to the variable x x = 10
- miahi 14y ago
  What's really annoying is that most of the time you see this kind of comment there is no explanation why 10 was chosen.
  - dhimes 14y ago
    And that's what comments really need to do: tell 'why.'
    - Pyrodogg 14y ago
      http://xkcd.com/221/ http://xkcd.com/221/
  - MetallicCloud 14y ago
    That's why you should use constants. Still self documenting without the need for comments (usually).
    - adamzegelin 14y ago
      const TEN = 12;
      - tehwalrus 14y ago
        #define true false
  - fudged71 14y ago
    In our embedded systems class we were required to define all of our constants, just to add another level of description to operations. It definitely helped to navigate spaghetti code.
- mikeash 14y ago
  At least it's better than: // set the variable x to 10 x = 12;
  - sixothree 14y ago
    sFile = "filename.xml"; then later sFile = File.ReadAllText("filename.xml");
  - zvrba 14y ago
    I think you've forgotten a leading zero ;)
bunderbunder 14y ago
Sadly, I fear that comments won't help in that situation. They could, except that the solution depends critically on the developer realizing they're writing garbled code during the time they're writing it. I don't know about anyone else, but my code's never garbled when I write it. It only becomes garbled by magic, and only when I don't look at it for a few weeks. Or, strangely enough, the moment someone else looks at it. Still haven't figured out a reliable enough garble detection mechanism that my employer's willing to pay for.

mjbellantoni 14y ago

"A large proportion of the comments I see should actually be function or method names for a more well factored version of the block of code that follows." I share the same experience.

RegEx 14y ago

This point gets brought up a lot, but I'm not going to complain at all. In fact, just 5-6 months ago I used to be one of those programmers who would do # gets the xml def get_xml(): It took comments like this to help me realize just how silly the whole thing was. Now I write as much self-documenting code as I can, but comment as needed.

bonch 14y ago
It's all subjective, but that comment could be expanded to, for example, explain where the XML is assumed to be coming from or what kind of XML is expected. If the code makes no assumptions about those things, that is also something to write a comment about.
Funnnny 14y ago
Sure. Comment should be "why I did this", and code should be "how I did this", some people just write in "what did I do" and walk away thought they have comment Code took from a project I'm working with: #End of package
- StavrosK 14y ago
  I generally become aware that I should leave a comment whenever I write something that is less than trivial (but exactly less than trivial) to write/understand. Longish list comprehension? Summarize what it does. Nested function calls? Summarize why. Etc.
- chii 14y ago
  > Comment should be "why I did this", and code should be "how I did this" the problem starts when the 'why' doesn't match the 'how'...which one is "correct"?

ozgung 14y ago

This may be a valid argument for modern languages like Ruby or Python. For 90s' coding standards however comments are even MORE important than the code itself. For Assembly and C programming and for low level graphics and physics algorithms proper naming of variables and functions are never enough for readable code.