Beefy Boxes and Bandwidth Generously Provided by pair Networks
There's more than one way to do things
 
PerlMonks  

Re: Re: •Re: Re: Re: Re: Re: Re: What should be returned in scalar context? (best practice)

by !1 (Hermit)
on Dec 22, 2003 at 11:21 UTC ( #316359=note: print w/replies, xml ) Need Help??


in reply to Re: •Re: Re: Re: Re: Re: Re: What should be returned in scalar context? (best practice)
in thread What should be returned in scalar context?

I've decided that there's no changing your opinion on the matter. Despite the fact that four people have responded questioning your use of "returns an array", you have stood fast. You called my expectations of an arrayref in scalar context when you say "returns an array" as ridiculous and I certainly appreciate your input on the matter. It does show, however, that there's at least one idiot who reads "returns an array" this way. You state here that you can say "returns an array" and you won't need to update the documentation in the future. I mean no disrespect when I say that I read that as you intentionally use abstract terms and "golf" your documentation to lower the amount of maintainence needed. If this is the case, why bother at all? If you aren't going to properly describe your code in non-ambiguous terminology then what good does your documentation serve?

But hey, I'm just a dimwit who believes "returns an array" means that the subroutine returns an arrayref in scalar context. =/

  • Comment on Re: Re: •Re: Re: Re: Re: Re: Re: What should be returned in scalar context? (best practice)

Replies are listed 'Best First'.
Re+: What should be returned in scalar context? (best practice)
by BrowserUk (Pope) on Dec 22, 2003 at 12:52 UTC

    If it helps any, you may offset me against, that list of 4, as one in total agreement with sauoq's position on this. So, 4:2. Any advance?

    It makes no sense whatsoever, that every piece of documentation, for every sub, in every module, that ever "returns an array", should have to repeatedly, re-document, re-clarify and re-explain the details of the consequences of this behaviour.

    It is already well docemented in the perl documentation. This is one of those things that everyone coming to perl for the first time, doesn't understand, falls foul of, perhaps rants against until they understand the efficacy of contextual behaviour, but then learns and understands.

    As for interpreting "returns an array", to mean "returns an array reference in a scalar context", I think that you called it on that one.


    Examine what is said, not who speaks.
    "Efficiency is intelligent laziness." -David Dunham
    "Think for yourself!" - Abigail
    Hooray!

      But hey, I'm just a dimwit who believes "returns an array" means that the subroutine returns an arrayref in scalar context. =/
      As for interpreting "returns an array", to mean "returns an array reference in a scalar context", I think that you called it on that one.

      Hmm. As !1's roommate I understand what he means by that. The entire point of this thread has been whether or not "returns an array" makes sense of documentation. I'm with !1, Juerd, merlyn, and company on this one. "returns an array" to describe the behavior that a subroutine returns a list of values in list syntax and the number of elements in scalar context is PISS-POOR documentation. It's great as a comment. It tells exactly what it does. However, when I see "returns an array" in documentation I don't know what it means. Why not? Because I've seen it used in two ways. For stuff that has to run under mod_perl, I usually take it to mean that it returns an arrayref under scalar context. If that's the case then I usually yell at !1 because usually he's the one that writes that documentation. For everything else, I usually think it means that the author of the module never gave any thought whatsoever to what the subroutine should return in scalar context. Why? Simple. There are a lot of programmers who never even consider it. Some think list and array mean the exact thing and will say that their subroutine returns an array yet the subroutine behaves like a list would on the RHS of the assignment operator. I'm not telling you to not use "returns an array." That would be rude. I'm just asking for clear documentation. That's it. That's what everyone on the other side of the fence is asking for yet you knuckleheads are denying us. If you were to say, "behaves like an array on the RHS of the assignment operator", "Context: behaves like array", or even "behaves like an array, from a context standpoint" I'd say, "Gee golly, this guy really knows how to write clear and concise documentation." But you won't. So I guess I'll mark it down in my notebook, "BrowserUK and saouq would prefer putting their comments in the documentation so read their documentation as such."

      antirice    
      The first rule of Perl club is - use Perl
      The
      ith rule of Perl club is - follow rule i - 1 for i > 1

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others studying the Monastery: (9)
As of 2021-09-24 15:23 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found

    Notices?