| Message ID | 20190731162434.12837-1-volodymyr_babchuk@epam.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | CODING_STYLE: clarify function argument indentation | expand |
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
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
> 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
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
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.
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
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.
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
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.
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(+)