in reply to Re: Easily catalog subroutines with a synopsis comment
in thread Easily catalog subroutines with a synopsis comment

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

Replies are listed 'Best First'.
Re^3: Easily catalog subroutines with a synopsis comment
by Herkum (Parson) on Apr 19, 2008 at 19:16 UTC

    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.

        The module name is EEBL::Game, and it is called (eventually) via the public API of playball. I would hope that when I reference my API's within the context of a specific module that they make sense.

        I wonder if writers and linguistics would make a better programmers than a mathematicians? The ability to express yourself clearly in your code, to often seems to be a secondary concern for too many programmers.