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.
Re:C folk
jarich on 2007-08-30T10:45:43
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, algorithms used...
Re:Opinions...
jplindstrom on 2007-08-31T15:13:00
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.Re:Opinions…
Aristotle on 2007-09-01T15:17:35
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.
Re:section separators
schwern on 2007-08-31T00:53:29
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.
Re:section separators
Aristotle on 2007-09-01T15:20:07
Funny, I wrote an article about that just recently.
Re:Pod--
Aristotle on 2007-09-01T15:19:24
Don’t sprinkle POD into the middle of your code.
Re:Pod--
jjore on 2007-09-01T18:24:49
Well sure, that's a problem too.
