in reply to Re: More comprehensive style guide for Perl docs than perlpodstyle?
in thread More comprehensive style guide for Perl docs than perlpodstyle?

Yes, I dislike non-named optional arguments to functions ... especially when there's more than one! Much prefer to handle optional arguments via a single hashref argument because I feel this scales better over time - to support a new optional argument simply support a new key value in the hash with a sensible default and old code keeps on working without modification.

This is especially important in functions taking more than three parameters because humans are better at remembering names than orderings - as indicated by the Perl Best Practices guideline "Use a hash of named arguments for any subroutine that has more than three parameters". BTW, as indicated at Named Subroutine Parameters: Compile-time errors vs. Run-time warnings, the "reason" given for a hash reference (rather than a hash) was an error in the book: anonymous hash population is done at run-time, not compile-time; that said, Conway still stands by this advice because "Error messages that point users to the right place are definitely worth the (tiny) overhead of passing named args in a hash".

An example of a Perl internal function with a poor interface is split, which has two (update:three) optional arguments and much surprising magic such as ' ' vs / / vs // vs /^/ as the first argument; empty leading fields preserved, empty trailing fields stripped by default; negative LIMITs; and many more. I feel split would have been much clearer and more manageable over time, if instead of using optional arguments (and special magic values for parameters) it had used a single named hashref argument to specify tricky behaviour.

Replies are listed 'Best First'.
Re^3: More comprehensive style guide for Perl docs than perlpodstyle?
by hippo (Archbishop) on Jan 07, 2019 at 09:51 UTC
    An example of a Perl internal function with a poor interface is split, which has two optional arguments ...

    Agreed. There is another function with two optional arguments which annoys me more, however, and that is substr. Even though I've read the documentation thousands of times I never quite believe that LENGTH is the optional argument and OFFSET is mandatory. Every time I go to use substr and know that it's "the wrong way round" it is just so illogical to me that I still have to pause and consult the docs again just to make sure.

[reply]
      This one is easier to remember if you know of languages with functions like LEFT, RIGHT, and MID (or MIDSTR).
      And substr is the equivalent of MID, while you obviously see it as LEFT … 
      # untested, as usual :-) and without the "replace" functionality
sub midstr   { return substr(shift, shift, shift); }
sub leftstr  { return substr(shift, 0, shift); }
sub rightstr { return substr(shift, -shift); }

      [download]
[reply]
[d/l]

      As indicated at Re: Drunk on golf: 99 Bottles of Beer, there's another reason to dislike substr - it's way too long for golf! (compared to Python's slices). :) Also, I'm not a fan of using substr as an lvalue - it may be powerful but adds still more complexity and does my head in.

[reply]
      And I just noted that the interface for substr looks suspiciously similiar to that of splice (LEFT → shift, RIGHT → pop)
[reply]

      I would actually find that illogical. The function is called substr and not left (as soonix already indicates). So for me it is logic to provide a start and an end index. And personally I hate it when people create optional arguments somewhere in the middle of an argument list and so I love it how substr is defined.

[reply]

        It is heartening to hear that you love it. OTOH, this just makes me sigh:

        perl -E 'say substr ("Hello World!", 5);'
[reply]
[d/l]

In Section Seekers of Perl Wisdom