Re: Easily catalog subroutines with a synopsis comment

[hardburn]

in reply to Easily catalog subroutines with a synopsis comment

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.

[jdporter]

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().

[Herkum]

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;
}

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.

[BrowserUk]

What's the name of the module this comes from?