Beefy Boxes and Bandwidth Generously Provided by pair Networks
Don't ask to ask, just ask
 
PerlMonks  

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

by Juerd (Abbot)
on Dec 21, 2003 at 23:00 UTC ( [id://316257]=note: print w/replies, xml ) Need Help??


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

Nevermind. You're not getting it. If you document only what your code does, you might as well just duplicate the source.

You say that my argument is "overly academic with no practical basis". Perhaps it is. It's not something I have considered. I'm just someone who hates documentation that is wrong and vague where it could be correct and clear if the author cared.

Technically and linguistically, you're wrong if you say that a Perl non-lvalue subroutine returns an array. Write one sentence more and your documentation is correct and clear.

Instead of Returns an array of foos. just write Returns a list of foos. (In scalar context, returns the number of foos.) and stop making people guess what you mean.

If you insist on redefining the word 'array', go ahead. But don't forget to document your meaning of the word.

I am perfectly aware that functions always return a list. Does that mean I'm going to stop documenting that a function like sub f { return 0 } "returns a scalar?" Somehow I doubt you'd take issue with that even though it isn't technically true. That function is, afterall, returning a list. The list simply has one element.

No, it is perfectly acceptable to call a one-element list a scalar in this context. However, it is not very customary to mention that the single value you return is a scalar. Usually, we talk about "a number" or "a string". "Returns true", "returns the integer portion", "returns a string", "returns the number of". In fact, no function in perlfunc is documented to return a scalar.

However, it is customary to indicate that a collection of numbers or strings is returned by using the word "list", because such a collection is called a "list" in Perl jargon.

By the way, why do you think my argument has no practical basis? That's nonsense. Consistency with existing jargon and documentation is very practical.

Your argument, if applied evenly, would require the abolishment of the phrase "returns a scalar" as well.

Saying that a function returns a scalar isn't even wrong, even if the function returns 15 scalars, it still also returns a scalar. It would be misleading, though, so I'd avoid it. But as I said, it is not common to say that a function returns any scalar at all. We usually describe what the scalars are, since we assume every Perl coder knows that normal (non-lvalue) subs can only return scalars.

Fortunately, we won't have to do that, because your position is completely untenable.

I'm wasting my time. You're even more stubborn than I am. Even when presented with facts and prior art, you refuse to see that what you do is different from what others have agreed on.

By saying your function "returns a scalar" or "returns an array" or "returns a list" you are able to describe exactly how code the is written without trying to describe how Perl works.

A sub returns a foo or a list of bars. You don't document that a function returns a scalar or just a list. But if you do, that's acceptable. Documenting that a function returns an array is *not acceptable* if it does not return an array. Is that so hard? Don't say your function returns 2 if does not return 2. And don't say your function returns 1+2 if it has return 1+2 in it. It returns 3. Stick to the facts and keep it simple (but never make it inaccurate). This is technical documentation, not prose.

The reason it makes sense to say those things is that context is imposed before the value is returned.

Actually, it depends on how you look at it. Context is propagated to every single return statement, and to the last statement of the sub.

When you return @ret; the list returned is composed of elements generated by evaluating @ret in the required context. If it is in scalar context, you get the number of elements of @ret. If it is in list context, you get all of the elements of @ret. Likewise, if you return (33, 42); the list returned is created by evaluating (33, 42) in scalar or list context as necessary.

That is correct. But even if you have return @foo, @foo, the array, is never returned. It cannot be referenced or mutated. The thing that is returned is not an array. The function does not return an array, ever.

It's very simple. You can call something an array if it starts with @. Because lvalue subs are reasonably new, some work-around syntax is needed to actually use an lvalue sub as an array: @{\foo} instead of just foo, and that too proves my point that only if it starts with @, it is an array.

Note that I'm not saying that everything that does start with @ is an array. It could be a slice.

This rule also means that in $foo[0], $foo is not the array. @foo is the array. Another typical aspect of arrays is that you can use them in array context, like the context imposed on the first argument of push. If you can't push @{\foo()}, "bar";, foo did not return a regular array. If it did return an array and it doesn't work, that is because it was made readonly or magical (tied).

Obey gravity, it's the law.

In other words, there is always a disconnect between what you return and what Perl returns.

Better described as "there can be a disconnect between syntax and semantics". And API documentation is about explaining what happens, not about how you make that happen.

$i++; # increment $i # silly.
Comments should describe the "why";
Documentation should describe the "what";
Code describes the "how".

Perl is already well-documented.

And it is time to document your own code well too. Perl set the example, now all you have to do is follow that example. Perl is well known for it's high quality documentation, but wouldn't have been if perlfunc did crazy things like tell people that some function returns an array.

If keys returned an array, not only would it return a list of elements in list context and a number of elements in scalar context, it would also be spliceable. And pushable, and shiftable. And the best of all: it would be referable. Yes, that is silly. But that is what returning an array is.

Juerd # { site => 'juerd.nl', plp_site => 'plp.juerd.nl', do_not_use => 'spamtrap' }

This is my last node in this discussion. I am unable to convince you. You would defy gravity if you could. I just hope other people who read this thread did learn from it, and don't say that functions return arrays.

Log In?
Username:
Password:

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

How do I use this?Last hourOther CB clients
Other Users?
Others having an uproarious good time at the Monastery: (3)
As of 2024-03-28 13:57 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found