Beefy Boxes and Bandwidth Generously Provided by pair Networks DiBona
Your skill will accomplish
what the force of many cannot
 
PerlMonks  

Re: Easily catalog subroutines with a synopsis comment

by hardburn (Abbot)
on Apr 18, 2008 at 13:17 UTC ( #681486=note: print w/ replies, xml ) Need Help??


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
Re^2: Easily catalog subroutines with a synopsis comment
by jdporter (Canon) 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

      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.

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://681486]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others browsing the Monastery: (16)
As of 2014-04-23 20:47 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    April first is:







    Results (554 votes), past polls