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.
On Saturday, April 25, 2020 at 3:38:29 AM UTC-4, Lutz Horn wrote:
>
> > 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
>
--
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/golang-nuts/aa98f3ae-f44f-4603-bdb1-ea9a36a5dc00%40googlegroups.com.
