http://www.perlmonks.org?node_id=681486


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.

"There is no shame in being self-taught, only in not trying to learn in the first place." -- Atrus, Myst: The Book of D'ni.

  • Comment on Re: Easily catalog subroutines with a synopsis comment

Replies are listed 'Best First'.
Re^2: Easily catalog subroutines with a synopsis comment
by jdporter (Paladin) on Apr 18, 2008 at 13:26 UTC

    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
[reply]
[d/l]

      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.

[reply]
[d/l]
[reply]

In Section Meditations