in reply to Re: Documenting Methods/Subs
in thread Documenting Methods/Subs

There is no such thing as too much documentation, no matter how redundant it may be.

It can get to the extreme, very easily. Consider a simple sub to commify a number, called commify_number. There's no need for this to have a description of what it does - it's obvious. Large blocks of comments (or comments documenting most of the lines of code within the sub) for something like this are going to obscure what should be a relatively simple thing.

My thoughts: if code is getting lost in a sea of comments, there's too many comments. Redundancy is largely irrelevant if the comments themselves are stopping you seeing what's going on.

While I agree that a lack of docs is bad, it's very important to get some sort of balance between code usability (in a maintenence sense) and understanding, at least in my mind.

-- Foxcub