On Mon, 2007-05-14 at 02:16 -0400, Mathew Snyder wrote:
> Is it possible to use too many comments? I'm looking at a script I wrote and
> think I may have made it less clear by trying to make it more clear.
Absolutely.
Commenting in a useful clear way I believe takes years to master.
Maintaining your own and other scripts will teach you the difference.
Note the following bad sample
# loop through each entry of the xyz table.
foreach my $key (sort keys xyz) {
It is also very important to document WITH your code. Take the above
snippet and consider just changing the variable from non-specific to
problem domain, eg $key to $account. It makes it clearer.
foreach my $account (sort keys xyz) {
Look to the code itself first, use real names and spell them in full. I
have a production system where prefix is shortened to pfx, pref, prefx.
It is a nightmare to maintain.
Use paragraphing, keep lines of code that go together with a blank line
above and below.
something account related;
something customer related;
something else customer related;
work out totals for the report;
Generally clearer code is more important than clearer comments.
Coding is a craft. Simple to learn the basics, years of mastery to get
it right.
Ken
--
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
http://learn.perl.org/
