[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Xen-devel] [PATCH] CODING_STYLE: clarify function argument indentation


  • To: Volodymyr Babchuk <Volodymyr_Babchuk@xxxxxxxx>
  • From: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
  • Date: Wed, 31 Jul 2019 19:10:34 +0100
  • Authentication-results: esa5.hc3370-68.iphmx.com; dkim=none (message not signed) header.i=none; spf=None smtp.pra=andrew.cooper3@xxxxxxxxxx; spf=Pass smtp.mailfrom=Andrew.Cooper3@xxxxxxxxxx; spf=None smtp.helo=postmaster@xxxxxxxxxxxxxxx
  • Autocrypt: addr=andrew.cooper3@xxxxxxxxxx; prefer-encrypt=mutual; keydata= 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 6+ahAA==
  • Cc: Stefano Stabellini <sstabellini@xxxxxxxxxx>, Wei Liu <wl@xxxxxxx>, Konrad Rzeszutek Wilk <konrad.wilk@xxxxxxxxxx>, George Dunlap <George.Dunlap@xxxxxxxxxxxxx>, Tim Deegan <tim@xxxxxxx>, Ian Jackson <ian.jackson@xxxxxxxxxxxxx>, Julien Grall <julien.grall@xxxxxxx>, Jan Beulich <jbeulich@xxxxxxxx>, "xen-devel@xxxxxxxxxxxxxxxxxxxx" <xen-devel@xxxxxxxxxxxxxxxxxxxx>, "viktor.mitin.19@xxxxxxxxx" <viktor.mitin.19@xxxxxxxxx>
  • Delivery-date: Wed, 31 Jul 2019 18:10:45 +0000
  • Ironport-sdr: obb9FS6rog4JzkBAN17OdKG8RuMVFUWNMWZe6RxbpwA7TZkwZMBjAk4JwjM2DmAzQWsGgic6lo D8gCJJC/JwqXbmT0ZlhXSlzRAQfV7XwLQv04ntxnuKGSvN+Sy4FWewZo+brbsGUeIKl88LemfL nS90aDIq9MnuCclDLCgNTjBIAeebiK8xkA6evCd2vHkfMswo3P73uG9ZEWMtvqy3MPYSkdX+J6 Fw1c1DQgt+dxefA2JAfCDB9zktIbM5vHxKubBQzBZILtx34gQ4gfFaxkenGW9OCp1UXmvJb4b4 aBw=
  • List-id: Xen developer discussion <xen-devel.lists.xenproject.org>
  • Openpgp: preference=signencrypt

On 31/07/2019 18:49, Volodymyr Babchuk wrote:
> Hi Andrew,
>
> Andrew Cooper writes:
>
>> On 31/07/2019 17:24, Volodymyr Babchuk wrote:
>>> There are coding style rules that are widely accepted by community,
>>> but newer were formalized in the document. Notable example is the
>>> question on how function arguments and parameters should be indented
>>> when they do not fit into one line.
>>>
>>> This question was raised multiple times lately, mostly because of
>>> ongoing efforts to create Xen coding style formatting tool and because
>>> of new community members, who are not aware of such unwritten rules.
>>>
>>> Actually, this rule is already implicitly defined in the document by
>>> defining emacs coding style: 'c-file-style: "BSD"'. In this mode emacs
>>> lines up function arguments under the first argument. Naturally, most
>>> of Xen code is written in this style.
>>>
>>> So, lets state the obvious and fix this rule explicitly.
>>>
>>> Signed-off-by: Volodymyr Babchuk <volodymyr_babchuk@xxxxxxxx>
>>> ---
>>>  CODING_STYLE | 14 ++++++++++++++
>>>  1 file changed, 14 insertions(+)
>>>
>>> diff --git a/CODING_STYLE b/CODING_STYLE
>>> index 6cc5b774cf..6479215a15 100644
>>> --- a/CODING_STYLE
>>> +++ b/CODING_STYLE
>>> @@ -53,6 +53,20 @@ Line Length
>>>  Lines should be less than 80 characters in length.  Long lines should
>>>  be split at sensible places and the trailing portions indented.
>>>
>>> +For multiline function declaration and call each new line should be
>>> +aligned with the first the parameter or argument. e.g.:
>>> +
>>> +void my_function_with_long_name(struct lengthy_struct_name *struct1,
>>> +                                struct lengthy_struct_name *struct2,
>>> +                                struct lengthy_struct_name *struct3);
>>> +
>>> +or
>>> +
>>> +function_with_so_many_params(wordy_parameter1, wordy_parameter2,
>>> +                             wordy_parameter3, wordy_parameter4);
>>> +
>>> +The same applies for macros.
>> For very wordy functions, or ones with silly quantities of parameters,
>> the following is also acceptable
>>
>> void my_function_with_long_and_silly_name(
>>  struct lengthy_struct_name *struct1, unsigned int womble, unsigned
>> int whatsit,
>>  struct lengthy_struct_name *struct2, bool yes, bool no, bool maybe,
>>  bool file_not_found, struct lengthy_struct_name *struct3, struct
>> lengthy_struct_name *struct4);
>>
>> which you will find in a few places throughout the code, because the
>> above doesn't waste enough vertical space to fit several functions in,
>> and push all the relevant details to the RHS.
> Excuse me, what it RHS?

Right Hand Side.

Sorry - I was being lazy when typing.

>
>> Per the above rules, the result would be this:
>>
>> void my_function_with_long_and_silly_name(struct lengthy_struct_name
>> *struct1,
>>  unsigned int womble,
>>  unsigned int whatsit,
>>  struct lengthy_struct_name
>> *struct2,
>>  bool yes, bool no, bool maybe,
>>  bool file_not_found,
>>  struct lengthy_struct_name
>> *struct3,
>>  struct lengthy_struct_name
>> *struct4);
>>
>> Of course, this is also a sign that maybe the function signature wants
>> changing anyway, but that may not be possible/sensible at the time.
>>
>> As with everything, the coding style is a set of guidelines which are
>> applicable to 98% of cases, but there are cases where aren't
>> appropriate, and common sense is the only reasonable deciding factor.
> I totally agree with you. Probably we should either add a generic clause
> like "This coding style rules may be violated if they produce weird
> results".

We should have a general clause (rather than specific ones), but I'd be
hesitant to word it like that.

How about:

These guidelines are expected to be applicable to all circumstances.  If
the result looks weird, consider whether this is the wisest way to solve
the problem in the first place, or whether an exception may be warranted.

The advantage here is if we see the same kind of exceptions being
requested repeatedly, then perhaps this is a hint that the coding style
should be modified.

> Or we can add clarification to this particular rule: "Do not break
> parameter definition to multiple lines. If parameters are too long,
> decrease indentation, but try to line them up. e.g.:
>
> void my_function_with_long_and_silly_name(
>         struct lengthy_struct_name *struct1,
>         unsigned int womble,
>         unsigned int whatsit,
>         struct lengthy_struct_name *struct2,
>         bool yes, bool no, bool maybe,
>         bool file_not_found,
>         struct lengthy_struct_name *struct3,
>         struct lengthy_struct_name *struct4);
> "
>
> What do you think?

The specific example I gave used exactly 4 spaces, consistent with the
rest of the style.

At the point that we are trying to reclaim space, reclaiming as much as
possible is the obvious move.

The above case is actually easy to spot in an automated fashion
(function declaration/call, open bracket, newline, indentation by one
block, subsequent lines on at the same indentation), and while it is
something which I wouldn't expect an automated tool to recommend, all
that matters is that it leaves it alone if it finds it.

~Andrew

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/xen-devel

 


Rackspace

Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.