[Perl-beginners] Thoughts on comments

If you look at Spamassassin's codes,you'll find its comments are more
than codes.One thing I'm not satisfied with in perl is that why it
does'nt support the multi-lines comments like /*...*/ in C.

The / is taken, but there are many other ways to do multiline comments.
For one, see perldoc perlpod.

You mean using =begin, =end? They are not exactly multiline *comments*.

Not that I use them myself, but the "proper" (for various values of
proper) way to use POD for multi-line comments is

=for comment
Commented text
=cut

Yes it sucks, yes it will be fixed* in Perl 6* (or possible earlier if
the trend of adopting Perl 6 features in Perl 5 releases continues).
It will be a quote-like operator, so you will be able to say

#{
This is
a multi-line comment
}

#[
so is this
#[ and this one is nested ]
]

#{{{ multiple brackets must match on both sides }}}

* for various definitions of fixed, there are some caveats, the
biggest being that a # as the first character on a line is always
considered a single line comment even if the next character is a
bracketing character. Don't ask me why.

* http://dev.perl.org/perl6/doc/design/syn/S02.html

Yes, it is very easy to have too many comments, especially if you are
using them in the wrong way. The purpose of comments is to tell the
story of why something is the way it is is, not to tell people what
the code does. The variable and subroutine names should tell that
story.

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

On 5/15/07, Ken Foskey wrote:
snip
snip

The problem here is not the shortening (which can be a good thing),
but the lack of standardization. Each organization should put
together a style guide (preferably based on Conway's Perl Best
Practices*) that includes common abbreviations.

* http://www.oreilly.com/catalog/perlbp/

I personally agree with this.But for most programmers whose mother
language is not english,wrote those comments would spend much more time
than coding time.You may say that they can write comments with their own
languages,but doesn't like windows office,under unix environment people
mostly couldn't write non-english words conveniently.

Jeff,

Your messages get treated wrongly too.

The end up twice on the perl beginners list, with the same Message-ID,
and have a Newsgroups: header field with the groupname twice in it, just
like Chas's messages.

Message-ID: <[email protected]>

The diff:

7c7
< Received: (qmail 12545 invoked from network); 15 May 2007
15:34:12 -0000
---
15:33:32 -0000

9,10c9,10
< by lists.develooper.com with SMTP; 15 May 2007 15:34:12 -0000
< Received: (qmail 11236 invoked by uid 225); 15 May 2007 15:34:12 -0000
---
12c12
< Received: (qmail 11225 invoked by alias); 15 May 2007 15:34:11 -0000
---
18c18
< by la.mx.develooper.com (qpsmtpd/0.28) with ESMTP; Tue, 15 May
2007 08:24:52 -0700
---
2007 08:33:24 -0700

21c21
< b=ZlUseYiluSL6dQjukGf7x6oeK1J2LyLpdIfrvbiUfrYR8eVnoa0m+o1xO7ryVI2Q;
---
37c37
< X-ELNK-Trace:
7070c57df59c6c2974bf435c0eb9d4780e74e32b2412d3e602759962c1c6f405dcaa4df6
116241b5350badd9bab72f9c350badd9bab72f9c350b
add9bab72f9c
---
7070c57df59c6c2974bf435c0eb9d4780e74e32b2412d3e663eb761851f44a575458a107
158c2e4b350badd9bab72f9c350badd9bab72f9c350b
add9bab72f9c

Again this 10 minutes difference at the start. Did
somebody(AT)develooper.com switch on a bad type of greylisting?

Right, the problem has to be at la.mx.develooper.com then. The
chances of both Google and Earthlink screwing up in the same way is
very unlikely.

Ask, are you the admin?

I don't know what happened.I've changed from my premium Earthlink to
free Yahoo/GMX accounts.But seems the problems still exist.So I don't
think there was something wrong about me.