A lot of monks here (and good programmers in general) favour terse comments directly in the code, along with substantial POD. They likely have the same doubts you do.

I've used a style much like that for a long time, though. I was first exposed to it in a C-shop, and I have seen several advantages with it:

• Maintenance programmers don't have to read code for every sub
• Explicitly states the contract for a function/method
• Leaves room for prose (e.g. ToDo lists, caveats the programmer notes, modification histories for non-CVS environments)
• Clearly separates methods and routines from one another
• Clearly separates general comments from comments about specific lines of code

That said, the better I get at Perl programming, the more my comments tend towards brevity, so I'm pretty sure those wiser monks who dislike this style are on to something.

Like indentation, I think they are a matter of local style. The advantage is they make an easily spotted pattern for documentation of a function in code that is intended to be desk-checked. The baroque kind of framing you show is trained into many eyeballs, in variations for dozens of languages.

IMO, pod makes more sense for perl. Going directly from code comments to documentation is a fine thing.

=head2 get_records

   my @foo = get_records( $dbh , "select * from BAR..." );

=cut

sub get_records { # ...
}
[download]

Comments are not documentation ;)

*links here*

I avoid documenting private subroutines with POD.

POD implies public.

POD only implies pod and sexy.

=for private =head2 get_records
   my @foo = get_records( $dbh , "select * from BAR..." );

=cut

=begin private

=head2 get_records

   my @foo = get_records( $dbh , "select * from BAR..." );

=end private

=cut
[download]

MJD says "you can't just make shit up and expect the computer to know what you mean, retardo!"

I run a Win32 PPM repository for perl 5.6.x and 5.8.x -- I take requests (README).

** The third rule of perl club is a statement of fact: pod is sexy.

What I have seen is that this style of comment (in particular) tends to grow less accurate as it passes through iterations of maintenance. Eventually it becomes just wrong, for example referring to parameters that are no longer used, or describing the original purpose that no longer applies.

And if you don't trust the comment, you have to read the code, and if you end up reading the code then why bother with this type of comment in the first place.

It could also be argued that this style of comment is a form of code duplication, complete with the same maintenance issues. Of course I want to see helpful comments, particularly for dense or terse code, but frankly I've developed a form of comment-blindness, triggered by code like this:

/**********************************************
 * Copyright: Moneygrubbers, inc 1982-1984    *
 * ALL RIGHTS RESERVED                        *
 * System: Custom IEBGENER for CICS T1        *
 * Name:    MyFunction                        *
 * Created: 1 Jan 1982                        *
 * Author:  asmith                            *
 * Purpose: Apply foo algorithm to bar data   *
 * Returns: bptr - ptr to modified bah        * 
 * Mod: asmith                                *
 * Mod Purpose: bar is now baz                *
 * Mod Date: 2 Jan 1982                       *
 * Parameters: bar - ptr to bar               *
 * Parameters: baz - stack copy of bar        *
 * Known bugs: none                           *
 * Other comments: Hello, World!              *
 * Re-written by bjones 1998                  *
 * Code Status: UNREVIEWED                    *
 *********************************************/
[download]

(Exaggerated for dramatic effect)

This documentation format reminds me strongly of the one used by RoboDoc which I happen to like a lot since it can be used in almost any programming language (Perl, Java, C/C++, etc) and can generate output in HTML, XHTML, RTF and LaTeX.

If you can't convert your group to POD (which I agree is best for Perl programmers), at least it might be worthwhile to introduce them to RoboDoc since without much change of format and effort will allow automatic generation of documentation.

Hope this helps, -gjb-

I have my doubts about this style too :-)

#---------------------------------------------------------
# Function:   get_records (taken from process_member.pl)
# Arguments:  DB handle
#             sql query string
# Returns:    result array of SQL query
#---------------------------------------------------------

sub get_records {
   my ( $db_handle_ref, $sql ) = @_;
   my @recs;
# [...]
   return @recs;
}
[download]

Several issues:

First off, as several other people have pointed out, if this is documentation aimed at the users of the code then POD would be the preferred format. That way you get the support of a lot of POD:: modules for formatting and reading your documentation.

Second, look at what the comments tell you - or rather what they don't:

# Function:   get_records (taken from process_member.pl)
[download]

The function name and the filename it lives in. Both of which we already know (we're looking at the file to see the comment, and the subroutine name is part of the subroutines declaration.)

# Arguments:  DB handle
#             sql query string
[download]

The arguments are a database handle (to what?) and an SQL query string (of what format?). This gives us no more information that we would get from the first line of the function:

   my ( $db_handle_ref, $sql ) = @_;
[download]

It would be even easier if we called the database handle $dbh which would be familiar to all users of DBI, and a more descriptive name for the sql query.

Finally this:

# Returns:    result array of SQL query
[download]

Tells us, I think, that we get an array of the rows returned by the SQL query. This is:

• Phrased badly. I could read that as an array of SQL query objects rather than the results from the SQL query.
• It doesn't tell me what array consists of. Is it an array of hashes keyed of column names? An array of values in order? What?

All of this information is better expressed in the code itself. Rather than spending time writing comments that can easily get out of sync with the code, spend time writing clear expressive code. If you can't look at a subroutine and understand what it does rewrite it until you do. Break it into smaller subroutines, use better subroutine names, use better variable names, etc.

For example the original routine might be better expressed as (guessing it's actual use since the comment doesn't actually say :-)

sub fetch_matching_process_records {
   my ( $dbh, $sql_query ) = @_;
   my @process_records;
   # Something that populates @process_records with 
   # ProcessRecord objects with a known API
   return @process_records;
}
[download]

  return @recs;
[download]

  return \@recs;
[download]

It also would not be hard^* to write a parser to extract POD from the code.

^* In the sense that someone else has already done it. :)

I comment like the above. I borrowed this style from my learning back in the 80's and it was how most languages I learned suggested you comment. I hated comments, until I found myself programming in work. And had to revisit my own code. I specifically want to comment on functions and subroutines so I know what arguments and values are returned. This is easy for me as I update a function or subroutine I update the comment and know what the changes are and can quickly check the calls to the subroutine or function.

That said when the script goes live and I am no longer testing it, I trim down the comments and place them in more approiate places for the documentation. POD I am just beginning to explore fully and can not list all its advantages as I was introduced to pod as a means of creating user help files pod2usage. Though from coming here I am starting to see its full nature.

I think in general any commenting that is detailed is great. Converting it to other version is not hard. It would be easy to parse these scripts and change the commenting style. Remember commenting has set formats that perl needs to recognise to not execute comments. You can program a perl script to change your comments when the commenting style changes. So any commenting style can be updated if the need if you find the need to change style later.

So in the style of commenting I believe pod looks like the most flexible way to make your comments useful on many levels. On the decision to mark each function in the code, I appreciate that decision and highly second it.

Update I found this link but specifically an interesting comment on 2 pod || !2 pod:
Canta Forda Computer Laboratory

- Assumptions that the routine makes (e.g. a resource is locked by the caller before the routine is called; the routine isn't called very often so performance is not important and the implementation is simplified). Obviosly, you'll want to put in assertion-like sanity checks to handle these whenever you can, but there are cases where this is not possible and these may be buried (hence obfuscated) in the code.

- Limitations of the implementation and future changes that could be made. Many times this is something like an idea of how to improve performance (i.e. by introducing some complexity) if an assumption changes about how the routine will be used in the future.

Unfortunately, some project management types who believe that "more == better" get real pedantic and start mandating that all sorts of useless drivel appear here that is either quickly outdated and/or can be gleaned from the first two lines of the sub.

bluto