roles and code readability

Question

The improvement of using roles (Moo::Role or Role::Tiny or whatever)

with qw(
    Some::Role
    Some::Other::Role
);
...
some_roles_method();

over just explicitly importing the function from the mixin class

use Some::Role qw/some_roles_method/;
...
some_roles_method();

are numerous, and include added flexibility, less bookkeeping (especially if there are a lot of methods being imported), and not overwriting existing methods.

But a big drawback is if you're reading the code and come across mentions of some_roles_method() and you want to read the function, it's not immediately apparent where to go. All you can tell is that it's not defined in this file.

Are there any good strategies for handling that? Am I the only one that bothers?

Answer 1

The only thing I can think of, and that I do once in a while, is to document everything thoroughly with POD. But of course that requires a lot of discipline.

use Moo;
with 'Role::Reader', 'Role::Writer';

# ...

=head1 METHODS

=head2 frobnicate

Frobnicates the foo.

=cut

sub frobnicate { ... }

=head2 write_cheque

This method is documented in L<Role::Writer>.

=head2 write_autograph

This method is documented in L<Role::Writer>.

=head2 read_mind

This method is documented in L<Role::Reader>.

=head2 read_book

This method is documented in L<Role::Reader>.

=cut

1;