|
|
|
| Syntactic Confectionery Delight | |
| PerlMonks |
comment on |
| ( [id://3333]=superdoc: print w/replies, xml ) | Need Help?? |
|
If the eyes that will see the product may be anyone outside of yourself, you definite want to comment to a level just below your skill level. But 1 for 1 on comments is too much. For commenting perl, there's two levels that you want to do it at:
Make sure to comment-document every subroutine and 'global' variable that is used, to the point of what it does, the general idea of how it's done, a summary of expected parameters, and what return values that it gives. This should be at least a short paragraph for somewhat complex subs. This will help others that read your program to understand the purpose of subroutines and variables. This is also a good idea to carry this concept to any significant blocks of code (ie, the stuff between matched pairs of {}'s) so that that particular block is understood. At the other level, you should comment anything that perl can easily make arcane, namely things like regex's, maps, foreach/while/do loops, and other operations. Most of the rest of perl tends to be at least 'readable' assuming a sufficient understanding of perl, so things like print, open, and other statements don't need comments unless you do complex operations with them. But even trivial regex lines should be explains as to what they are. By doing this, not only do you make your code easily maintainable by someone that follows you, but you can also use it as a learning tool for those with less experience than you.
Dr. Michael K. Neylon - mneylon-pm@masemware.com || "You've left the lens cap of your mind on again, Pinky" - The Brain In reply to Re: Another commenting question,
by Masem
|
|