Jeff Law <l...@redhat.com> writes:
> On 05/02/2016 02:40 PM, Carlos O'Donell wrote:
>>
>> However, in the end, I think that yet-another-document is not the
>> solution we want. What we actually need is a program that just formats
>> your source according to the GNU Coding Style and that way you can always
>> tell your users "Run indent" and be done with it. The output of such a
>> program should always be considered correct, and if it's not, we should
>> fix it immediately.
>>
>> Why can't we use indent?
> Sadly, "indent" simply breaks c++ code.
>
> I think the solution here is clang-format with a suitable clang-format
> configuration file. One has been started (gcc/contrib/clang-format),
> but it's not yet complete.
How far are you intending to go with that though? I'd hate to see
a tool become the final authority on coding standards. For one thing
it means that everyone will need exactly the same version of clang-format
installed (a la autoconf) in order for all the submissions to agree.
If we ever did upgrade to a newer version, the formatting rules for the
codebase are likely to change en masse to whatever the new clang-format
says is correct. Presumably we might need to keep more than one version
of the formatter around, depending on which branch we're working on.
And sometimes there are multiple acceptable ways of writing the same code.
Which wins is an aesthetic choice, which tools tend to be bad at handling.
E.g. if a parameter list is too long for a line, there's often a choice
of how to balance the parameters across multiple lines, with some being
more readable than others. I wouldn't want the one chosen by a formatting
tool to be the only acceptable one.
And sometimes people split "if" conditions over multiple lines even when
they would fit on one line, since the split version seems more readable.
Again I wouldn't want a tool to be the final judge of which is right.
Also, reformatting a statement over more lines isn't always the best way
of dealing with long lines. Sometimes it's better to split it into separate
statements instead. That too is a choice that tools are bad at making.
(E.g. if you introduce a temporary variable, what should it be called?)
There are exceptions to rules too. E.g. I don't think it's required
to end a comment with a full stop if the comment ends with code.
/* This is to handle statements like:
i++; */
is IMO correct, rather than:
/* This is to handle statements like:
i++;. */
or:
/* This is to handle statements like:
i++;
. */
I doubt any tool is going to be good enough to make that kind of
distinction. (E.g. you can't rely on the semicolon if quoting
Fortran code, or a .def style macro invocation.)
And if the tool isn't the final authority, and it does still remain
a human choice, then...
>> At the end of the day I never want to see another comment about code
>> formatting because the user used X and X always formats code correctly.
> Amen.
...this kind of comment is still going to occur. And clear documentation
should help when it does.
Also, coding standards and the scope of Bernd's document are more
than formatting. E.g. take your comment in a recent thread about not
adding "()" when referring to a function in comments. Even clang-format
is unlikely to be smart enough to know whether a particular () is
acceptable or not. (It would be acceptable in a quoted code snippet
but not in a normal sentence.) Also, the tool wouldn't know when
argument names need to be capitalised in comments, etc. Sometimes
argument names are English words and comments contain a mixture of
both uses. Bernd's document talked about those kinds of details too.
Sorry for the rant :-) Maybe I'm just jaded by past experience with
automatic formatting tools. E.g. we internally use(d?) check_GNU_style.sh
to check patches before submission and it seemed to produce far more
false positives than true positives. (I'm not sure it ever produced
what I'd consider a true positive for me, although I did sometimes do
what it said even if I disagreed, as the path of least resistance.)
That's not to say the script is bad, just that it shouldn't always be
taken literally.
Obviously clang-format is smarter than check_GNU_style.sh but I think
the same principle applies.
Thanks,
Richard
