On the curiously overvalued nature of comments in source

We use subversion at work. A piece of code is refactored, such that a method that was previously called from one site is now called from another. Co-worker who did the refactoring left the old code in, commented out, and then placed above it:

# this is now called in <new call site>

Separately, a new routine was added to a source file and it concludes with:

# everything works
return 1;

In a third case, I see the following:

# if the volume doesn't exist, fail
return 0 unless -d $vol and -w $vol;

When did programmers stop understanding how to read code? Where did the notion that large blobs of editorial constitute good practice? (And don't get me started on density-reducing formatting practices, like turning a one- to two-line conditional into six lines comprised mostly of whitespace and a delimiter. It is not more readable!) Here's my position: comments are not documentation. Comments are context-providing quick notices to explain a rationale or behavior that can not be gleaned from the source itself. You changed something between two revisions? Write a commit log. Writing code effectively requires familiarity, which requires going over the code to determine what it does - no amount of commenting is going to change that, so don't use that as a rationale. Worse, comments have to be maintained - and ditto for perldoc/doxygen. We have a case of a function that used to return a hash now returning an object, so access to fields has been replaced with method calls of the same name. The perldoc, however, hasn't been updated, so an unfamiliar user would get the wrong idea. Write real documentation - concise, to the point, detailing overall behavior. Make interfaces self-documenting as much as possible by using legible, meaningful identifiers. In dynamic languages without type declarations, add a docstring and simple validation that spits out the correct usage (I love that I can type help(some_object) in Python and get a printout of how to use it in just a few lines on screen). Above all, use good tools! Too many bad commenting and nomenclature habits (appending a comment to indicate the end of every function, most Systems Hungarian atrocities, etc are a function of people not using their IDEs; dynamic language programmers writing inane comments is a symptom of not using interactive environments to explore the tool domain) simply come down to improper tool usage. These things are out there for you to take advantage of. Please, for the love of programmers everywhere, do! I think there's a misperception that entrée to a piece of code should be trivial. No, doggie. A programmer spends more time reading code than writing it, so acknowledge that situation and make that fact useful. Comment on unintuitive or grossly unfamiliar things. Don't make him waste his time reading your code to learn absolutely nothing. Thank you.