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

[Vaibhav Gupta]

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