A modest format suggestion

[Scott Deerwester]

I greatly appreciate the fact that Go has a coding standard. I have a modest proposed modification. Instead of this:

    // Great is a really great function.
    func Great(
        anArg int, // This explains anArg
        anotherArg string, // This explains anotherArg
    ) (err error) {
    ...

I'd think that this:

    // Great is a really great function.
    func Great(
        anArg      int,    // This explains anArg
        anotherArg string, // This explains anotherArg
    ) (err error) {
    ...

would be both clearer and more consistent with this:

    var (
        aVar       = 12          // This explains aVar
        anotherVar = "something" // This explains anotherVar
    )

or this:

    type SomeStruct struct {
        FieldName string
        Value     int
    }


    var aStructList = []*SomeStruct {
        {
            FieldName: "SomeName", // Comment for FieldName
            Value:     12,         // Comment for Value
        },
    }

which are already part of the standard coding style. Is this the right place to make such a proposal?

[Saied Seghatoleslami]

Doesn't this style of writing assume that there are a lot of arguments to be passed to function which I think is not a good practice since it makes it much harder to remember what the function does and how to call and most importantly, how to debug it when becomes necessary?

So, if there are a lot of arguments to be passed to the function, it is best to redesign it and use a data structure that encapsulates the arguments.  Otherwise, what is wrong with this?

// Great is a really great function anArg does this and anotherArg does that.
func Great(anArg int, anotherArg string) (err error) {
return nil
}

--
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 golang-nuts...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/golang-nuts/8a4fa305-a8bc-4512-8f23-6a42b479dd2d%40googlegroups.com.

[sc...@doozee.net]

I think that these are independent questions. While I agree entirely with your comments on avoiding lots of parameters, and bundling them in a struct if it gets out of hand, helping clarity is of value whether no matter how many arguments there are. By analogy:

var aStructList = []*SomeStruct {
        {
            FieldName: "SomeName", // Comment for FieldName
            Value:     12,         // Comment for Value
        },
    }

and

var aStructList = []*SomeStruct {
    // Comment about the following entry
    { FieldName: "SomeName", Value: 12 },
}

or

var aStructList = []*SomeStruct {
    { FieldName: "SomeName", Value: 12 }, // Comment about the entry on this line
}

are both perfectly fine (aren't they?).

To unsubscribe from this group and stop receiving emails from it, send an email to golan...@googlegroups.com.

[Ian Lance Taylor]

There is a fairly high bar for gofmt changes these days, but it's not
possible. The right approach is to discuss it here, and then if there
is some kind of consensus follow the proposal process outlined at
https://golang.org/s/proposal. Thanks.

One useful metric would be look at some real Go code (that you didn't
write) and how often people use this style. I suspect it's pretty
rare in the standard library. One problem with this style is that (I
think) the argument comments don't show up in godoc, which makes them
hard to discover by people who just want to use the package.

Ian

[Lutz Horn]

> Instead of this:
>
> |
> // Great is a really great function.
>     func Great(
>         anArg int,// This explains anArg
>         anotherArg string,// This explains anotherArg

> )(err error){

> ...
> |
>
> I'd think that this:
>
> |
> // Great is a really great function.
>     func Great(
>         anArg int,// This explains anArg
>         anotherArg string,// This explains anotherArg
> )(err error){
> ...

Two arguments why this is not needed and would encourage bad coding
practice.

* If the names `anArg` and `anotherArg` don't reveal intention, they are
bad names. It should be encouraged to change them to intention revealing
names.

* The comment for the whole function should describe the meaning of the
parameters, if necessary. This comment is shown by IDEs, comments on
parameters are not. It should be encouraged to write complete function
comments.

Lutz

[sc...@doozee.net]

Ian's and Lutz's responses get to the heart of how comments on parameters are different from comments on struct field, constant and variable initializations, namely that the documentation framework (whether in an IDE or via godoc) elevates comments on functions to a different status than "internal" comments. It's reasonable to reflect this in the coding style. I don't find Lutz's argument regarding variable names as related to the clarity of the format of the comments. Of course variables should have good names and, yes, the variable names in this contrived example are bad names. That doesn't mean that the programmer shouldn't also provide further explanation of what the variables are all about (if needed) in the form of a comment. Even well-named variables can benefit from an explanation in a comment.

That said, the point is well taken that programmers should be encouraged to keep in mind that the comments on the function as a whole are "public" in a sense that other comments are not. I'd still argue that, for the sake of programmers looking at the source code, aligning types and comments is easier to grok than not doing so, but this value is mitigated by that of hinting, via the format, that end of line comments on function arguments are of lower importance than comments on the function as a whole.

In any case, thanks for an informative and friendly discussion. It was enlightening, and I won't pursue this proposal further.

[rgul...@saintmarys.edu]

Perhaps I need to read more of the Beginner's Guide first, but wouldn't (err error) be an inherent protection against variable number of "ghost" arguments (such as in python), if that is what this question is about?  (But maybe it is only about formatting, I cannot be too sure, as again, I am unfamiliar with most of the language syntax.

[Warren Stephens]

Or really "Go for it" and suggestion a language syntax enhancement!

   // Great is a really great function.
    func Great(

        anArg      int,    /// This explains anArg
        anotherArg string, /// This explains anotherArg
    ) (err error) {
    ...

Where 3 slashes `///` indicates that the comments should be vertically aligned -- which may be useful in other situations as well.

[Leszek Kubik]

It wasn't mentioned here but I really like how C# IDE helps understanding function arguments. It's entirely true that arguments should have meaningful names but sometimes it's impossible. Standard C# function comments let you document arguments. The argument comment appears right when you need it, when you are at a point of providing a value for it. I haven't seen such thing in Go yet. You can provide additional info about the arguments inside function documentation but it's not standardised the way a common Go IDE would understand it. In practice I sometimes jump to the function definition to clarify the meaning of the argument but it could be more explicit.