No such thing as a small change | |
PerlMonks |
Re^4: Why no comments?by BrowserUk (Patriarch) |
on Feb 01, 2009 at 23:24 UTC ( [id://740601]=note: print w/replies, xml ) | Need Help?? |
what I thought I'd done was to describe in broad terms what I consider to be the attributes of good commenting, Your opening line is: "It is indeed a sad state of affairs when programmers fail to properly comment as they write code." And that sets the tone for the entire post. For the rest. When I encounter modules that contain that much verbiage I often just delete it without reading it. Especially when I encounter comments like
To "document":
Three lines of verbiage (including 2 blanks) mostly redundant. And completely redundant if the documentation is placed in the only verifiable content of the file--the code. And
to "document"
Again, mostly redundant, with the code being far clearer than the "documentation". And the whole lot would be clearer still (and far more efficient to boot), written as:
Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
"Science is about questioning the status quo. Questioning authority".
In the absence of evidence, opinion is indistinguishable from prejudice.
In Section
Seekers of Perl Wisdom
|
|