in reply to Documenting Methods/Subs

I don't comment small subroutines that are "obvious". Like a routine called max. However, a lot of subroutines assume things - they are called preconditions. Personally, I think it's vital to document those. I also tend to document arguments if the sub has many optional arguments (in which I prefer to use named parameters - if you pick good names, just listing which parameters can be used is often enough).

It's not a black & white thing. I think that both those that document all subs and that document none are wrong. Good programmers know which subs to document and which subs can be left undocumented. ;-)

Abigail

Replies are listed 'Best First'.
Re: Re: Documenting Methods/Subs
by Rex(Wrecks) (Curate) on Jan 10, 2003 at 18:42 UTC
    ++!! This is the method I use as well. There are a few other guidelines I use:
  • More than 2 args, document the args so I remember what the hell I'm doing when I come back to the code in 6 months :)
  • Keep it short enough that a programmer can figure it out, and it doesn't take up to much screen space. If you need more than that, it should probably go in the help section.

    With that, and common sense, it is usually pretty obvious to me what I need to put in th comments.

    "Nothing is sure but death and taxes" I say combine the two and its death to all taxes!
[reply]
Re: Re: Documenting Methods/Subs
by autarch (Hermit) on Jan 11, 2003 at 05:04 UTC

    This is actually a good reason to use a module like Params::Validate, it helps provide documentation for a subroutine/method.

    For example: 

     sub do_the_thing
 {
     my %p = validate( @_, { foo => { isa => 'Foo::Big' },
                             size => { type => SCALAR, default => 10 },
                             ...
                           } );
     ...
 }

    This way all the possible named arguments are documented, as well as their types/classes, defaults, etc. Along with good names, this really does completely document what parameters are accepted, _and_ as a bonus does actual validation on them.

[reply]
      I'm not actually that much of a fan of enforcing object types in method signatures to be honest because it can lead to a certain amount of pain at testing time, especially if you're using the very lovely and worthwhile Test::Class. The 'Self Shunt' testing pattern is remarkably handy, that's when you do: 
      sub test_the_thing : Test {
    my $self = shift;
    ...
    $object_under_test->do_the_thing( foo => $self, ... )
    ...
}

sub called_from_do_the_thing {
    my $self = shift;
    ok array_eq(\@_, [qw/foo bar baz/];
}

      [download]
      and similar tricks. If you're enforcing the object type you have to draft in Test::MockObject, which is great, but is also substantially more complex.
[reply]
[d/l]

        If you're enforcing the object type you have to draft in Test::MockObject, which is great, but is also substantially more complex.

        You can still use the self-shunt unit testing pattern with enforced object types and Test::Class if you take advantage of perl's run-time method dispatch.

        For example, consider a class that takes an optional logging object to allow custom logging on an object by object basis.

        Read more... (2 kB)
[reply]
[d/l]
[select]

        I'm not actually that much of a fan of enforcing object types in method signatures to be honest because it can lead to a certain amount of pain at testing time, ... 

        my %p = validate( @_, { bar => { can => 'do_that_thang' } } );

        [download]
[reply]
[d/l]

In Section Meditations