Re: An abridged "Writing C" for the gcc web pages

[Carlos O'Donell <carlos at redhat dot com>]

On 05/03/2016 03:59 PM, Richard Sandiford wrote:
> Jeff Law <law@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?

As far as it takes to make the process of submitting patches less
painful for new contributors and sensible for maintainers?

If we end up with one tool per branch then we did it wrong. In glibc
I'm happy to retroactively say the newest formatting tool is always
right for all branches barring expert intervention.

> And if the tool isn't the final authority, and it does still remain
> a human choice, then...

We *are* the community, so yes, there is a final line in the sand where
a sensible expert maintainer may tell you "yeah but" and ask you to change
the code to make it more legible. However, 99% of the changes are now just
going to be automatic.
 
>>> 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.

Yes, it will occur, but the frequency should be much reduced. I also agree
that clear documentation helps, so I don't disparage Bernd's work here,
I think it's great. I just think that the most important next step here
is a submission code formatting tool.

> 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.

Agreed. That's minor.

> 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.

That's a shame and a clear indicator the script is wrong or the technology
wasn't around for us to do the kinds of things we wanted.

> Obviously clang-format is smarter than check_GNU_style.sh but I think
> the same principle applies.

If we get one false positive out of the new checker we've done something
wrong. It should strive to give output that everyone agrees is 100%
correct barring optinal aesthetic choices. This way the tool is run, a
reviewer looks at the patch, and final comments are made on the style.

That's what I'd like to see for glibc. $0.02.

-- 
Cheers,
Carlos.