If I were to answer this in a few words, I'd say:
Pick a style, and adhere to it when possible.
One should write code such that it appears to do what it actually does. This also means that one should write code such that bad code appears to be bad. Joel of "Joel on Software" has an interesting write-up called Making Wrong Code Look Wrong touching this subject. He's talking about Hungarian Notation which you may not want to use, but the underlying idea is very important.
Almost all of the comments I've seen in my lifetime were completely useless, and what should be documented wasn't. The most important thing to document are the assumptions you (the programmer) made. For example, "$var must not be undef.", "This algorithm is only ideal for lists no bigger than XXX elements.", "The module may not be thread-safe." and "Uses features specific to Win32." are all valuable comments which document assumptions. These bits of information are not apparent from reading the code, therefore they must be documented.
On a less general note, I have a beef with documentation that fails to properly the causes and methods of failure of a unit. Very little is usually said about how a function might fail. I feel it's very important to document the state of relevant variables, structures and objects on failure.
Update: I incorrectly used the word "comment" where I meant "document". Fixed.
In reply to Re: Meaning of Maintanability and Functionality in Coding Perl
by ikegami
in thread Meaning of Maintanability and Functionality in Coding Perl
by neversaint
| For: | Use: | ||
| & | & | ||
| < | < | ||
| > | > | ||
| [ | [ | ||
| ] | ] |