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

[Vaibhav Gupta]

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
>> _______________________________________________
>> devel mailing list
>> devel at rtems.org
>> http://lists.rtems.org/mailman/listinfo/devel
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20200404/a32f8cae/attachment.html>