Re: Subroutine Bewilderment

[Joost]

Calling conventions
Unless you really, really know what you're doing you should use subroutine($arg1,$arg2); to call any subroutine. AFAIK there is now no type of subroutine that MUST be called with a leading ampersand or without comma's seperating the arguments.

For methods; always use $object_or_class->methodname($arg,$arg2);

prototypes
If you use prototypes you can make it a little easier to use the other calling conventions but in general it's not needed unless you really want to write a subroutine that looks like a sort of operator on code blocks. Be sure to read up on prototypes before use, and only use them when you really need to.

defining and use of subs
If you don't use the default calling convention, you should define your subs (or a stub) before calling them. Subroutines that use "external" lexical variables that need to be intialized before calling should also be defined before calling (but that's just because you probably want the lexical initialisation near the definition of the sub).

summary
If you want to be safe, define your subs first and always use subroutine($arg,$arg2) unless you have a good reason not to.

Joost.

[dimar]

AFAIK there is now no type of subroutine that MUST be called with a leading ampersand or without comma's seperating the arguments

hmmm ... I could have emphasized more the 'definition' I was considering for MUST and MUST NOT. In other words, think of it like a kind of puzzle, can I write code in such a way that violating the rule will cause an error or a warning?. Then, if you find an answer to the puzzle, consider whether the code is likely to happen in the 'real world' ... if 'yes', then you have a candidate for MUST and MUST NOT. I have found this approach to be useful because it essentially asks "how many different ways can I (legally) say the same thing?"

For example, here is code that illustrates the ampersand 'rules'.

### init
    use strict;
    use warnings;
### ampersand variants
    fooFunc (1,2);      ### ok, ampersand optional
    &fooFunc(1,2);      ### ok, apersand optional

    #foneFunc(1,2);     ### NOT ok, called too early
    &foneFunc(1,2);     ### ok, ampersand required

    #fwoFunc(1,2);      ### NOT ok, too early
    &fwoFunc(1,2);      ### ok, ampersand required
    print "\n--------------------------\n";

sub fooFunc {
    if($_[0]){print "fooFunc arg0: ". $_[0] ."\n"}
    if($_[1]){print "fooFunc arg1: ". $_[1] ."\n"}
    print "-------------\n";
}

sub foneFunc() {
    if($_[0]){print "foneFunc arg0: ". $_[0] ."\n"}
    if($_[1]){print "foneFunc arg1: ". $_[1] ."\n"}
    print "-------------\n";
}

sub fwoFunc($$){
    if($_[0]){print "fwoFunc arg0: ". $_[0] ."\n"}
    if($_[1]){print "fwoFunc arg1: ". $_[1] ."\n"}
    print "-------------\n";
}

As far as a subroutine call where separating commas MUST NOT be included, consider a user-defined subroutine that works like map CODEBLOCK ARRAY putting a comma between CODEBLOCK and ARRAY causes error.

Note that we don't run into problems until we start introducing prototypes, which generally people say to "stay away from", which is fine, but with caveats...

• For someone used to programming in JavaScript (for example) it's not entirely obvious that fooFunction() is anything more than just a bare declaration of a subroutine name (as opposed to a 'prototype' embodied in the empty parenth).
• You can only 'stay away' from something for so long, and then finally you want to become one of those mythical people who 'really really really know what they are doing'
• It's interesting to know whether the 'stay away' items are either 1) legacy stuff that is going to be deprecated, or 2) advanced stuff that will remain for those who wish to delve deeper.
• It seems like some 'stay away' items that are advanced, overlap with 'stay away' items that are to be deprecated.

[Joost]

Note that we don't run into problems until we start introducing prototypes, which generally people say to "stay away from", which is fine, but with caveats...

Well... that's what prototypes are meant for: breaking the rules, and that entails you're taking the risk of confusing the users of your library, the perl parser, or both.

You can only 'stay away' from something for so long, and then finally you want to become one of those mythical people who 'really really really know what they are doing'

I understand your concern, but I can only repeat the above paragraph. The phrase "enough rope to hang yourself" comes to mind.

[doom]

Joost wrote:

Note that we don't run into problems until we start introducing prototypes, which generally people say to "stay away from", which is fine, but with caveats...

Well... that's what prototypes are meant for: breaking the rules, and that entails you're taking the risk of confusing the users of your library, the perl parser, or both.

I don't think this is a satisfactory summary of what prototypes are for. The way I would put it is that prototypes are included to let any programmer write something that behaves like one of the perl built-ins rather than a "normal" subroutine. They're there so that you can write things that work like

 $card = pop_random(@deck)

that deals from the middle of the deck instead of the top the way pop would.

As far as the main question is concerned, I can really only think of a couple of things to say, and they're pretty obvious. When there's always more than one way to do it, it's incumbant on the user of a subroutine to check the documentation, looking for examples of how to use it in the SYNOPSIS. And it's incumbant on the original programmer to document the code, and make sure there's a SYNOPSIS with decent examples in it.

If by some strange unheard of quirk of misfortune you're working with an undocumented code base, there's always the source...