From: "R. Joseph Newton" <[EMAIL PROTECTED]>
> If you are doing this for a dissertation, presentation will be
> important. So also will be commenting. It is not a bad idea to add a
> short comment for each variable you declare to indicate what role it
> plays in terms of the whole. You also should precede each function
> definition with comments describing: => What input parameters the
> function takes => What, if anything, the function returns => What
> processing the function offers--what is its purpose and describing
> each in precise terms
Since this is Perl this description should go into a POD, not a
comment.
I'd say one thing ... when commenting code do not assume the person
who will read them is a genius who knows the program inside out, but
also do not assume he's a dumbass. Do not explain that
$counter++ # increments the counter
;-)
Also ... often the much more important information is "what is the
function used for", not "what it does". What it does is usualy easy
to understand from the code, but why ... Though this is more true
about things like SQL stored procedures.
Jenda
===== [EMAIL PROTECTED] === http://Jenda.Krynicky.cz =====
When it comes to wine, women and song, wizards are allowed
to get drunk and croon as much as they like.
-- Terry Pratchett in Sourcery
--
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
