Ø // Add two numbers
Ø Add(x, y int) int
Although I support documenting functions as you did above, I feel that this
example doesn’t serve your argument well. In this specific case the
counter-argument would be that the documentation adds nothing at all to the
user’s understanding of the function, hence it is superfluous. Indeed, the
documentation doesn’t mention that the two numbers have to be int’s, so I’m
forced to also read the function declaration anyway. It’s like putting a
useless comment on a line of code, for example:
A = A + 1 // Add 1 to A
I expect that we can all agree that this comment is not only useless, but is
actually bad since it distracts the user for no benefit.
Regardless, as I said, I do support the documentation line in your example
simply because of human nature. It’s often better to have a rule (all
functions must be preceded by documentation) than to leave it up to the
programmer to decide on a case-by-case basis. The result is higher quality
code overall, I believe.
Let’s look at another example. Which form is better? Which tells the user
more? Which requires less documentation?
Power(x, y int) int
Power(base, exponent int) int
Yes, I think that using named parameters (both calling and return) is good in
general. Yes, there are cases (such as Add) where it doesn’t help, but it also
doesn’t hurt.
John
John Souvestre - New Orleans LA
From: Thomas Bushnell, BSG [mailto:[email protected]]
Sent: 2017 February 22, Wed 11:01
To: John Souvestre; golang-nuts
Subject: Re: [go-nuts] Re: Trying to understand := and named return values
Function parameters are not a good place (in general - there are exceptions) to
document arguments.
// Frob the outer otter.
FrobOuterOtter(otter Otter)
is not better than
// Frob the outer otter
FrobOuterOtter(Otter)
from the standpoint of external documentation.
But if you want the function to have access to the parameters, you need to name
them. The same is not true for return values.
// Add two numbers
Add(x, y int) int
is fine. This is silly:
// Add two numbers
Add(x, y int) (sum int)
Since the comment already says in English what is returned, there isn't any
value to repeating it again in the return value. Except when there are multiple
ones and the order matters:
// Lookup returns the name and email address of the user.
Lookup(id Identity) (name, email string)
On Tue, Feb 21, 2017 at 6:46 PM John Souvestre <[email protected]> wrote:
I feel the opposite. I view named returns as documentation of a function's
parameters. I'm constantly amazed by the (correct) emphasis placed on using
appropriate names for calling parameters, but not for the return parameters.
The goal is that I shouldn't have to read a function's code to use the
function, right?
So how can the disparity be justified? Oh, and the longer the function is the
more benefit there is to using them.
John
John Souvestre - New Orleans LA
-----Original Message-----
From: [email protected] [mailto:[email protected]] On
Behalf Of Ian Lance Taylor
Sent: 2017 February 21, Tue 16:13
To: [email protected]
Cc: golang-nuts
Subject: Re: [go-nuts] Re: Trying to understand := and named return values
On Tue, Feb 21, 2017 at 1:46 PM, <[email protected]> wrote:
> Seems like named returns + if/for/switch initializers = a shadowing
> nightmare. I wish the Go compiler emitted a loud warning on shadowing, as
> this is a dangerously subtle problem out there.
Yes, named returns may have been a mistake. Only use them in very
very short functions.
Ian
--
You received this message because you are subscribed to the Google Groups
"golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected]
<mailto:golang-nuts%[email protected]> .
For more options, visit https://groups.google.com/d/optout.
--
You received this message because you are subscribed to the Google Groups
"golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected]
<mailto:golang-nuts%[email protected]> .
For more options, visit https://groups.google.com/d/optout.
--
You received this message because you are subscribed to the Google Groups
"golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
For more options, visit https://groups.google.com/d/optout.
