It's mainly a matter of style I guess. Having it easy to grep through files can be important indeed. I got other projects which are slowly ported to C++ and originally had a coding style where a grep '^funcname' * -r worked nicely.

With the new coding style, where the return type is on the same line as the function name, that isn't that easy anymore.

As much as I see that this is a nice style, as much I fear duplication of documentation. I usually document every function/method (that belongs to the public API), with an extensive pod comment, which results in a nice pod documentation. I don't think I could justify the, most of the time, duplicated effort of making a pod and a comment documentation. Just for grep.

Maybe there should be a tool that greps the code and extracts the documentation for every function instead. A podgrep tool, usage like this: podgrep <subroutine name> and would print out every found pod documentation for that sub.

Just my 2 cents :)

For your enjoyment podgrep 0.01. Stick it in your path. Defaults to cwd.

#!/usr/bin/perl
use strict;
use Pod::Find;
use Pod::PlainText;
use IO::String;

die "Usage $0 <sub name> <dirs>\n" unless @ARGV;

my $sub = shift @ARGV;
my @dirs = @ARGV ? @ARGV : ('.');
print "Searching for $sub in @dirs\n";
my %pods = Pod::Find::pod_find( {-verbose => 0}, @dirs );

for my $file ( keys %pods ) {
    open my $fh, $file or die "Can't read $file $!\n";
    local $/ = "\n=";  # split into pod paragraph chunks
    while (<$fh>) {
        next unless m/^(\w+).*\b$sub\b/i;
        chop;
        s/^(\w+)/=head1/;  # kludge to fix parser issue with isolated 
+tokens
        print "\n-----$file\n";
        my $io = IO::String->new($_);
        Pod::PlainText::pod2text($io); 
    }
}
[download]

I can't see a situation where a one-line comment could provide better documentation than just naming the subroutine better in the first place.

I for one would not want to have very_long_subroutine_names_littered_throughout_my_code_so_that_each_sub_is_documented_everwhere_it_is_used().

A word spoken in Mind will reach its own level, in the objective world, by its own weight

Some of my routines have long names, but they are not usually public API's. They are used internally there to give context when they are being called. I also try to use names so that they work well with variables that are being passed to help give context.

Here is an example that I used in reference to a baseball game I am writing.

#################################################
sub __playball_game_over {
    my $self   = shift;
    my $result = shift;

    return if $self->__playball_inning_get < 9;

    if ( $self->__playball_team_on('offense')->get_id eq
         $self->away_team->get_id) {
        return if $result->run_scored;
        return 1
            if $self->__playball_score_for('home_team') >
               $self->__playball_score_for('away_team');
    }
    elsif ($result->run_scored) {
        return 1
            if $self->__playball_score_for('home_team') >
               $self->__playball_score_for('away_team');
    }
    else {
        return 1
            if $self->__playball_score_for('home_team') !=
               $self->__playball_score_for('away_team');
    }
    return;
}
[download]

I try my best to avoid long names, but I will use them to clarify my code. Code should be written like it is going to be read.

That suggestion is just as bad as the one which directs to put a comment on the same line as a statement ...

$p = some-op ; # comment
[download]

... or asks to put a comment after a if or a loop block ...

if ( ... )
{
  ...
} # end of ... condition
[download]

... for they generate useless text to ignore, and unnecessary work when/if the time comes to modify code or comment.

For your original purpose, I would rather have a better (API) pod (or any other kind of documentation you like) which visually highlights the sub and describes it succinctly.

Then again I am opining on matters of style ...

Please offer an example of how to go about achieving the same end in a quicker/easier fashion. Currently I'm unable to see the points you raise as relevent and valid.

• The text isn't useless. I describe the use.
• Changing code often leads to changing comments, regardless of where they are. This synopsis is only likely to need updating as often as you change the meaning of the function name. With a stable API, that shouldn't happen.
• More detailed documentation, where warranted, is in no way precluded by adding a synopsis.
• I would find 5 lines of POD in each function I document with a synopsis more work, harder to ignore when editing, and much less suited to my original purpose.

I would find that code that reads like it is supposed to be doing would be better than comments or 5 lines of POD. If the code is complex than encapsulating it in a subroutine that describes what it does would be appropriate as well.

I am tired of crappy code that uses one or two letter variables, or subroutines that last for 500+ lines and the excuse for them not writing clearly because they can use "Comments" to describe what it is doing later. If they cannot write clear code, why do they believe that their comments are going to be any better?

The text isn't useless. I describe the use

To me, the proposed "synopsis" is useless (given sub name, source, possibly with comment and/or pod, ctags).

More detailed documentation, where warranted, is in no way precluded by adding a synopsis.

Synopsis of a sub would already be listed at the beginning of the (sub) documentation.

As for the original purpose of searching files with synopsis, assuming POD which has sub name on =item line ...

# GNU egrep.
egrep -A 5 '^=item.+<sub name>' <file list>
[download]

... adjust N (= 5 above) to your liking. Whole thing can be easily wrapped so that one would need to supply only sub name regex & file names.

What purpose does a list of one line routine summaries serve?

... same end in a quicker/easier fashion.

sub flip_pancake
[download]

Also more robust. As you say, this only goes so far, but your technique doesn't go much further.

The problem with your technique is that it doesn't scale well. Once a routine requires more text than you want on a line, you are tempted to abbreviate your comment unreasonably. Once you have more developers involved the technique is destroyed by formatters and pretty printers.

Comments and documentation are time and/or space travelers. When I write comments as you've described; and I have over years. I write them now and bury them in a time capsule; when I dig them up three years hence, I find I am a different person. A person who finds them useless for being redundant or for being obscure. It is for that future person that I should write.

The comments I am apt to put on that line are too close to the code. Not too close textually or lexically, but too close in meaning--they say the same thing almost the same way. They shed the same light as the code; by being so similar, they can be understood or misconstrued in the same manner as the code.

The more experience I have with comments that have aged, the less value I usually find in the brief ones.

Having a better tool than a simple grep helps; consider the B or C options to grep or things like ctags.

Be well,
rir

sub addrecord {
    #****m* DataFile/addrecord
    # USAGE
    # $bdlfile->addrecord([field => value, field => value...])
    # Create a record and initialize it according
    # to file format (POF, BDL)
    # RETURNS
    # obj ref DataRecord
    #***
    my $self = shift;

    my %data = @_;
}
[download]

I tend to add comments above the sub, usually only 1 line, and beginning the comments with ## to make them easier to search for.

## comment line
sub dothis {
[download]

Now for a brief rant. Too many programmers do not adequately document their code unless someone is standing over them wielding a club. Many find documentation an unpleasant task, however one of the strengths of Perl, TIMTOWTDI, can become a weakness for those who rely too much on "read the source". I give blogical ++ for sharing a simple technique that works for him, and may also work for others.

Fearest thou not to document, lest thy code shall be shunned by others

I tend to use this style as well.

I also tend to do my searching inside my editor, so it being on the same line isn't as important for me. If I need to find quickly which file the sub is declared in, I'll do a grep for the sub foo { line, but then I'll open that file in an editor and search for the line. I then have plenty of context on the screen to see above the declaration and below.

Helping get options for ways to document that may help other monks is a good thing, and the discussion has even more ways noted. I'd like to thank everyone who has something constructive to say on how they document their code.