Proposal to add rule for nested CPP Directives in RTEMS coding conventions

[Vijay Kumar Banerjee]

On Mon, Apr 13, 2020 at 8:57 PM Joel Sherrill <joel at rtems.org> wrote:

> First, I appreciate the effort and probably agree with the FreeBSD rule.
> Can you post a link?
>
> https://www.freebsd.org/cgi/man.cgi?query=style&sektion=9

> I'm just not getting the nested rule out of the discussion so far. I can
> see a sequence like this being covered:
>
> #if
> #elif
> #else
> #endif
>
> But not this:
>
> #if
>   #if
>   #else
>   #endif
> #endif
>
> The latter is nested conditionals to me.
>
> Also does any of this cover whether it is all in column 1 or in the second
> case, is an indentation allowed?
>
> I have seen code where you are a few indentations levels in from the
> normal program logic and then an ifdef appears. If it is in column 1, the
> indentation flow is broken. If it follows the program indentation, does the
> condition code indent another level?
>
> For most cases, putting it in column 1 is OK because that's where it
> obviously goes by program logic. But in others, the code may look nicer it
> it is indented. I picked this file randomly because I suspected it had
> multiple cases of conditionals in it.
>
> https://git.rtems.org/rtems/tree/cpukit/rtems/src/msgqcreate.c
>
> It also has a decent example of having a section of code inside code that
> is already nested as being inside an if at line 114.
>
> This file is pure "start in column 1". But would the code at 114 look
> better if the #if were at the program logic level?
>
> Starting all the #if from column 1 makes it easier to note that there's a
preprocessor. This becomes
even more readable when the corresponding #elif and #else has a comment
mentioning the expression
in #if. Maybe writing comments should be added as a rule, along with the
rule for no indentation
for the preprocessor directives (?). The comments will already make it
easier to recognize the blocks
of code inside.

Just asking. We have a lot of feature conditionals in code.
>
> --joel
>
> On Mon, Apr 13, 2020 at 9:33 AM Vaibhav Gupta <vaibhav.varodek at gmail.com>
> wrote:
>
>> On Sat, 4 Apr 2020 at 01:44, Vaibhav Gupta <vaibhav.varodek at gmail.com>
>> wrote:
>> >
>> >
>> >
>> > On Sat, Apr 4, 2020, 1:41 AM Vijay Kumar Banerjee <vijay at rtems.org>
>> wrote:
>> >>
>> >>
>> >>
>> >> On Sat, Apr 4, 2020 at 1:22 AM Vaibhav Gupta <
>> vaibhav.varodek at gmail.com> wrote:
>> >>>
>> >>> CPP directives like:
>> >>> 1) #if
>> >>> 2) #ifdef
>> >>> 3) #ifndef
>> >>> 4) #elif
>> >>> 5) #else
>> >>> 6) #endif
>> >>>
>> >>> do form code blocks. Since, they don't make use of brackets,
>> >>> as a part of C language rule, their nested and repeated use
>> >>> can make the code very hard to read. Can even result it
>> >>> spaghetti code.
>> >>>
>> >>> This can be understood by this patch:
>> >>> https://lists.rtems.org/pipermail/devel/2020-April/058964.html
>> >>>
>> >>> The proposed idea is:
>> >>> 1) Nested CPP directives should follow same indentation rules
>> >>>     as of nested conditional statements like 'if' and loops.
>> >>>
>> >>> 2) To mark which closing CPP directive (#endif) pairs with which
>> >>> opening CPP directive (#if or #ifdef or #ifndef), make use of
>> comments.
>> >>> ex:
>> >>> #ifdef <some-macro> /* To test/verify/enable xyz */
>> >>>   .....
>> >>>   ....
>> >>> #endif /* To test/verify/enable xyz */
>> >>>
>> >> There's a rule like this in the FreeBSD
>> >
>> > Yes, and when I ported APIs, last year, as a part of my
>> > Project, the ported headers follow same rule.
>> >>
>> >> and we follow it in RTEMS-libbsd.
>> >> It is nicely explained in the FreeBSD style guide so I'm pasting an
>> excerpt
>> >> below:
>> >
>> > Thanks!
>> >
>> > --Vaibhav Gupta
>> >>
>> >>
>> >> "
>> >>     The comment for #endif should match the expression used in the
>> corre-
>> >>      sponding #if or #ifdef.  The comment for #else and #elif should
>> match the
>> >>      inverse of the expression(s) used in the preceding #if and/or
>> #elif
>> >>      statements.  In the comments, the subexpression "defined(FOO)" is
>> abbre-
>> >>      viated as "FOO".  For the purposes of comments, "#ifndef FOO" is
>> treated
>> >>      as "#if !defined(FOO)".
>> >>
>> >>      #ifdef KTRACE
>> >>      #include <sys/ktrace.h>
>> >>      #endif
>> >>
>> >>      #ifdef COMPAT_43
>> >>      /* A large region here, or other conditional code. */
>> >>      #else /* !COMPAT_43 */
>> >>      /* Or here. */
>> >>      #endif /* COMPAT_43 */
>> >>
>> >>      #ifndef COMPAT_43
>> >>      /* Yet another large region here, or other conditional code. */
>> >>      #else /* COMPAT_43 */
>> >>      /* Or here. */
>> >>      #endif /* !COMPAT_43 */
>> >>
>> >> "
>> >>
>> >> It would be nice to have a rule like this for RTEMS codes as well.
>> >>
>> >>
>> >>> --Vaibhav Gupta
>>
>> Should it be included then?
>>
>> -- Vaibhav Gupta
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20200413/3e350447/attachment.html>