Self-documenting code
I have a colleague who insists that his code doesn't need comments, it's "self documenting."

I've reviewed his code, and while it's clearer than code which I've seen others produce, I still disagree that self-documenting code is as complete and useful as well commented and documented code.

Help me understand his point of view.

  - What is self documenting code
  - Can it really replace well commented and documented code
  - Are there situations where it's better than well documented and commented code
  - Are there examples where code cannot possibly be self-documenting without comments

Maybe it's just my own limitations, but I don't see how it can be a good practice.

This is not meant to be an argument - please don't bring up reasons why well commented and documented code is high priority - there are many resources showing this, but they aren't convincing to my peer.  I believe I need to more fully understand his perspective to convince him otherwise.  Start a new question if you must, but don't argue here.

-Adam
Self-documenting code
===

I have a colleague who insists that his code doesn't need comments, it's "self documenting."

I've reviewed his code, and while it's clearer than code which I've seen others produce, I still disagree that self-documenting code is as complete and useful as well commented and documented code.

Help me understand his point of view.

  - What is self documenting code
  - Can it really replace well commented and documented code
  - Are there situations where it's better than well documented and commented code
  - Are there examples where code cannot possibly be self-documenting without comments

Maybe it's just my own limitations, but I don't see how it can be a good practice.

This is not meant to be an argument - please don't bring up reasons why well commented and documented code is high priority - there are many resources showing this, but they aren't convincing to my peer.  I believe I need to more fully understand his perspective to convince him otherwise.  Start a new question if you must, but don't argue here.

-Adam