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

[Joel Sherrill]

First, I appreciate the effort and probably agree with the FreeBSD rule.
Can you post a link?

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?

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/3f9734b3/attachment.html>