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

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

[Volodymyr Babchuk]

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@epam.com>
---
 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.
+
 User visible strings (e.g., printk() messages) should not be split so
 they can searched for more easily.
 
-- 
2.22.0

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

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

[Andrew Cooper]

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@epam.com>
> ---
>  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.

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.

~Andrew

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

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

[Viktor Mitin]

Hi All,

On Wed, Jul 31, 2019 at 7:45 PM Andrew Cooper <andrew.cooper3@citrix.com> wrote:
>
> 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@epam.com>
> > ---
> >  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.
>
> 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.

It might be hard to automate 'common sense' cases. It seems it would
be easier to find a solution on how to avoid such 'common sense'
cases.

One more open point with this rule is how to format the next case where:
len(return type string)+len(function name)+len(any of parameter) > 79

For example:
+some_long_return_type  my_function_with_long_name(struct
lengthy_struct_name *struct1,
+                                struct lengthy_struct_name *struct2,
+                                struct lengthy_struct_name *struct3);

Thanks

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

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

[Lars Kurth]

> On 31 Jul 2019, at 17:54, Viktor Mitin <viktor.mitin.19@gmail.com> wrote:
> 
> Hi All,
> 
> On Wed, Jul 31, 2019 at 7:45 PM Andrew Cooper <andrew.cooper3@citrix.com> wrote:
>> 
>> 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@epam.com>
>>> ---
>>> 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.
>> 
>> 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.
> 
> It might be hard to automate 'common sense' cases. It seems it would
> be easier to find a solution on how to avoid such 'common sense'
> cases.
> 
> One more open point with this rule is how to format the next case where:
> len(return type string)+len(function name)+len(any of parameter) > 79
> 
> For example:
> +some_long_return_type  my_function_with_long_name(struct
> lengthy_struct_name *struct1,
> +                                struct lengthy_struct_name *struct2,
> +                                struct lengthy_struct_name *struct3);
> 
> Thanks

Ultimately we have to make some trade-offs as to what is more important:
a) automatic style checking - which means "common sense" can't be formalised and there will be boundary cases like the above
b) reclaiming code review bandwidth through automation or going for a labour intensive manual approach

I suggest we discuss in tomorrow's community call how to approach this.
I think the most important first step is to have a good view on the kind of boundary cases that we may face

Lars 


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

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

[Volodymyr Babchuk]

Hi Lars,

Lars Kurth writes:

>> On 31 Jul 2019, at 17:54, Viktor Mitin <viktor.mitin.19@gmail.com> wrote:
>> 
>> Hi All,
>> 
>> On Wed, Jul 31, 2019 at 7:45 PM Andrew Cooper <andrew.cooper3@citrix.com> wrote:
>>> 
>>> On 31/07/2019 17:24, Volodymyr Babchuk wrote:

[...]

> Ultimately we have to make some trade-offs as to what is more important:
> a) automatic style checking - which means "common sense" can't be formalised and there will be boundary cases like the above
> b) reclaiming code review bandwidth through automation or going for a labour intensive manual approach
I like the linux kernel approach.  checkpatch.pl produces errors, which are
"no go", but it also produces warnings for such boundary cases, for
maintainer/reviewer to decide.

> I suggest we discuss in tomorrow's community call how to approach
> this.
Good idea, I'll attend.

> I think the most important first step is to have a good view on the kind of boundary cases that we may face
Then we need some volunteer who'll try to cover all corner cases.

-- 
Volodymyr Babchuk at EPAM
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel

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

[Anthony PERARD]

On Wed, Jul 31, 2019 at 05:57:32PM +0000, Volodymyr Babchuk wrote:
> Lars Kurth writes:
> > Ultimately we have to make some trade-offs as to what is more important:
> > a) automatic style checking - which means "common sense" can't be formalised and there will be boundary cases like the above
> > b) reclaiming code review bandwidth through automation or going for a labour intensive manual approach
> I like the linux kernel approach.  checkpatch.pl produces errors, which are
> "no go", but it also produces warnings for such boundary cases, for
> maintainer/reviewer to decide.

Yes! QEMU also uses checkpatch.pl script and I found that very useful
(both as reviewer and author of a patch). It tells you what are the
coding style violation in newly added code and doesn't try to reformat
the whole file.

But that script would needs quite a lot of rewriting, I think, to be
able to be used on the multiple coding style of xen.git.

-- 
Anthony PERARD

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

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

[Juergen Gross]

On 01.08.19 11:55, Anthony PERARD wrote:
> On Wed, Jul 31, 2019 at 05:57:32PM +0000, Volodymyr Babchuk wrote:
>> Lars Kurth writes:
>>> Ultimately we have to make some trade-offs as to what is more important:
>>> a) automatic style checking - which means "common sense" can't be formalised and there will be boundary cases like the above
>>> b) reclaiming code review bandwidth through automation or going for a labour intensive manual approach
>> I like the linux kernel approach.  checkpatch.pl produces errors, which are
>> "no go", but it also produces warnings for such boundary cases, for
>> maintainer/reviewer to decide.
> 
> Yes! QEMU also uses checkpatch.pl script and I found that very useful
> (both as reviewer and author of a patch). It tells you what are the
> coding style violation in newly added code and doesn't try to reformat
> the whole file.
> 
> But that script would needs quite a lot of rewriting, I think, to be
> able to be used on the multiple coding style of xen.git.
> 

We could start with only a few tests and enhance it later.

A good approach might be:

1. test commit message (e.g. is "Signed-off-by:" included, line
    length, ...)

2. add information which file is using which coding style, split
    patches to snipplets for each patched file, call style specific
    checker for each patched file (empty at the beginning)

3. re-use Linux kernel checkpatch.pl for checking kernel style files

4. introduce basic checks for Xen styles (e.g. indentation via spaces,
    line length checks, ...)

5. enhance Xen checks step by step


Juergen

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

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

[Volodymyr Babchuk]

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@epam.com>
>> ---
>>  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?

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

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?

Problem is that document will blow up quickly if we'll try to cover all
corner cases. So personally I stick to "generic rules + common sense"
approach.

--
Volodymyr Babchuk at EPAM
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel

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

[Andrew Cooper]

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@epam.com>
>>> ---
>>>  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@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel