My, the existance of the podlators of course!

Here's some example block comments (and the matching code that is being commented) I wrote when implementing chmod in Perl.

            # BSD documentation says 'X' is to be ignored unless
            # the operator is '+'. GNU, HP, SunOS and Solaris handle
            # '-' and '=', while OpenBSD ignores only '-'.
            # Solaris, HP and OpenBSD all turn a file with permission
            # 666 to a file with permission 000 if chmod =X is
            # is applied on it. SunOS and GNU act as if chmod = was
            # applied to it. I cannot find out what the reasoning
            # behind the choices of Solaris, HP and OpenBSD is.
            # GNU and SunOS seem to ignore the 'X', which, after
            # careful studying of the documentation seems to be
            # the right choice.
            # Therefore, remove any 'X' if the operator ain't '+';
            $perms =~ s/X+//g unless $operator eq '+';


                    # We know the operator eq '+'.
                    # Permission of `X' is special. If used on a regul
+ar file,
                    # the execution bit will only be turned on if any 
+of the
                    # execution bits of the _unmodified_ file are turn
+ed on.
                    # That is,
                    #      chmod 600 file; chmod u+x,a+X file;
                    # should result in the file having permission 700,
+ not 711.
                    # GNU and SunOS get this wrong;
                    # Solaris, HP and OpenBSD get it right.
                    next unless -d $file || grep {$orig {$_} & 1} @ugo
+;
[download]

=item B<X>

The execute permission bit, but only if the target is either a directo
+ry,
or has at least one execution bit set in the unmodified permission
bits. Furthermore, this permission is ignored if I<operator> is either
B<E<45>> or B<E<61>>.
[download]

-- Abigail

Of course I'm commenting subs! :-)

One note: There is, sometimes, a need to comment subroutines using '#' and not in POD. For instance, if you want to write notes to yourself or other coders (as opposed to users) about extremely specific TO DO items or whatnot, '#' comments can be more appropriate. OTOH, you can do something like:

=begin todo

Please change the variable names to something less cryptic. Anyone?

=end todo
[download]

I've been meaning to play around with the nifty-looking Pod::POM module which would make data gathering easy for stuff like this -- for instance, finding out all the TODO items for multiple projects at once.

Chris
M-x auto-bs-mode

One note: There is, sometimes, a need to comment subroutines using '#' and not in POD. For instance, if you want to write notes to yourself or other coders (as opposed to users) about extremely specific TO DO items or whatnot, '#' comments can be more appropriate.

Very true. My personal guideline is this:

• Interface - POD
• Implemenatation - Perl comment
/J