Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

schwern (1528)

schwern
  (email not shown publicly)
http://schwern.net/
AOL IM: MichaelSchwern (Add Buddy, Send Message)
Jabber: schwern@gmail.com

Schwern can destroy CPAN at his whim.

Journal of schwern (1528)

Thursday August 30, 2007
02:46 AM

On REALLY LOUD COMMENTS!!!

[ #34276 ]

A friend of mine who is learning how to code in a bioinformatics institute habitually asks me interesting basic questions about coding style. Here's one about REALLY LOUD COMMENTS and my reply.

-------------------------------------------------------------------------

tarchann wrote:
> All section headers and such in the code that my boss wrote that I am
> working with look something like this:
>
> ################################################################
> # Usage : bsml.pl TARGET [-f] listing_name FILE_PATH #
> ################################################################
>
> or
>
> ##################################################################
> # Loop on the subunit names provided
> #
> ##################################################################
>
> This is idiosyncratic, I reckon, not some kind of common documenting format?

Yep, he should be using POD for the usage stuff. Then you can do "perldoc bsml.pl".


        =head1 NAME

        bsml - something about what it does

        =head1 SYNOPSIS

            bsml.pl TARGET [-f] listing_name FILE_PATH

        =cut

        code here

It's also silly to put ".pl" or any other programing language extension onto the end of an executable program. That leaks out internal information to the user that they don't care about. It also makes it impossible to rewrite the executable in another language.

For internal comments about the code, he shouldn't be putting a big box of hashes around every comment. What that says is THIS IS REALLY IMPORTANT INFORMATION THAT YOU SHOULD REALLY PAY ATTENTION TO!!!! If you put that around every mundane little comment it defeats the whole purpose. A simple comment is sufficient.


        # Loop on the subunit names provided
        for my $name (@subunit_names) {
                code here
        }

Using big, loud comments blocks is a sign of someone who does not have a syntax highlighting editor and there's no excuse for that. Instead of making comments visually distinctive from the rest of the code using a different color and/or font they're making it distinctive by spewing hashes all over the screen.

Also, that's not a very useful comment as it just repeats what the code and variable names (should) already say. Just gets in the way of reading the code. Worse, it will fall out of date at some point, people don't maintain comments, and become a confusing lie.

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • I'm correcting a Perl-for-Biologists book that actually tells people to do it the wrong way because it's good practice. I see the same thing from CS majors just learning to program. It must be what they do in universities.

    I think the old biologists must be C folk, and they're passing on their bad habits. I might take a generation to get rid of all that crap.
    • It's what we did at university (The University of Melbourne, 1996-2001). Not for every comment, but for descriptions of the program at the top and above each function.

      This was through for two main reasons. One was an unawareness of syntax highlighting (many people were still using vi), but the more important reason was that the code was printed out for marking. Head tutors would compare the given output with the expected output, and then also mark on things like variable names, comments, code quality

  • Does anyone else find that POD mixed in with the code like that distracting?
    • No.

      And it keeps the docs next to what they document, reducing the risk of them getting out of sync.

      But it's just one of those debates that never end.
      • Documentation is good when it reads like prose. Code is hard enough to read without having to ignore large swathes of non-code gunk. A mixture of code and docs makes both much harder to read and write.

        If you want to be able to see docs and code at the same time, stop using Notepad and get a decent editor where you can have several windows open on the same file at different places.

        That’s my stance on this religious war.

  • what is your thought on ###### lines to separate sections of code?

    I find it ugly and distracting but have no other good logical argument against it.
    • The things which separate sections of code are called "subroutines".

      I'm more and more finding myself in the XP camp that comments mean complexity; if the code was simple and everything well named it won't need a comment. Complexity should be walled off into its own routine. That means if you find your code is complex enough to warrant a comment, or a separator, then you should consider an extract routine refactoring and a good routine name instead.
  • I wish people would use pod less because I find it personally mostly distracting to read. The markup looks too much like content. The shape isn't entirely unlike very short comments and the mandatory paragraph marks work against being able to read a chunk as a paragraph.

    I still use pod of course, I just don't like it and wish people found other ways to write docs.