standard for documenting conditional preprocessor directives?

standard for documenting conditional preprocessor directives?

[Robert P. J. Day]

  is there an understood standard for documenting conditional
preprocessor directives so you can more easily follow the logic in
lengthy code segments?

  consider:

    #ifdef SNAFU
    ... very long blah blah ...
    #else
    ... equally long woof woof ...
    #endif

  if you're perusing the code, and you hit the "#else" or "#endif",
it's almost impossible to tell what they correspond to, particularly
if they're mixed in with even more nested directives.  so what's the
best way to make this more readable?

  what about something like?

    #ifdef SNAFU
    ...
    #else /* !SNAFU */
    ...
    #endif /* !SNAFU */

  i contend that both of those new comments have value since, without
them, you wouldn't know what either the "#else" or "#endif"
represented.  but i'm willing to be disabused of that notion.

  thoughts?

rday

-- 
====================================
Robert P. J. Day
Linux Consulting, Training and Annoying Kernel Pedantry
Waterloo, Ontario, CANADA

http://crashcourse.ca
====================================

Re: standard for documenting conditional preprocessor directives?

[Robert P. J. Day]

On Mon, 27 Aug 2007, Andre Haupt wrote:

> On Mon, Aug 27, 2007 at 09:47:09AM -0400, Robert P. J. Day wrote:
> >
> >   is there an understood standard for documenting conditional
> > preprocessor directives so you can more easily follow the logic in
> > lengthy code segments?
> >
> >   consider:
> >
> >     #ifdef SNAFU
> >     ... very long blah blah ...
> >     #else
> >     ... equally long woof woof ...
> >     #endif
> >
> >   if you're perusing the code, and you hit the "#else" or "#endif",
> > it's almost impossible to tell what they correspond to, particularly
> > if they're mixed in with even more nested directives.  so what's the
> > best way to make this more readable?
> >
> >   what about something like?
> >
> >     #ifdef SNAFU
> >     ...
> >     #else /* !SNAFU */
> >     ...
> >     #endif /* !SNAFU */
>
> I would make that latter
> 	#endif /* SNAFU */
> instead, because the #endif refers to the #ifdef and not to the #else
> statement.

i thought of that but imagine that you're perusing code and you
remember that you'd already seen:

  #ifdef SNAFU

sometime later, you run across:

  #endif /* SNAFU */

now you're not sure if that's a simple end to "SNAFU" or possibly the
"#else" part that you missed during the perusal.  i'll grant you that
it looks a bit funny but, IMHO, it really does add more information
content, and has less chance of fooling you.

of course, none of the above works very well if the preprocessor
directive is some ugly, multi-part conditional, but there's not much
you can do about those anyway.

> sounds reasonable. Some people seem to hate comments in preprocessor
> directives though.

there's already lots of them in the code already, so the precedent has
already been set.  :-)

rday
-- 
====================================
Robert P. J. Day
Linux Consulting, Training and Annoying Kernel Pedantry
Waterloo, Ontario, CANADA

http://crashcourse.ca
====================================

Re: standard for documenting conditional preprocessor directives?

[Andre Haupt]

On Mon, Aug 27, 2007 at 09:47:09AM -0400, Robert P. J. Day wrote:
> 
>   is there an understood standard for documenting conditional
> preprocessor directives so you can more easily follow the logic in
> lengthy code segments?
> 
>   consider:
> 
>     #ifdef SNAFU
>     ... very long blah blah ...
>     #else
>     ... equally long woof woof ...
>     #endif
> 
>   if you're perusing the code, and you hit the "#else" or "#endif",
> it's almost impossible to tell what they correspond to, particularly
> if they're mixed in with even more nested directives.  so what's the
> best way to make this more readable?
> 
>   what about something like?
> 
>     #ifdef SNAFU
>     ...
>     #else /* !SNAFU */
>     ...
>     #endif /* !SNAFU */

I would make that latter
	#endif /* SNAFU */
instead, because the #endif refers to the #ifdef and not to the #else
statement.
> 
>   i contend that both of those new comments have value since, without
> them, you wouldn't know what either the "#else" or "#endif"
> represented.  but i'm willing to be disabused of that notion.
> 
>   thoughts?
> 
sounds reasonable. Some people seem to hate comments in preprocessor directives
though.

regards,

Andre

Re: standard for documenting conditional preprocessor directives?

[Randy Dunlap]

On Mon, 27 Aug 2007 09:47:09 -0400 (EDT) Robert P. J. Day wrote:

> 
>   is there an understood standard for documenting conditional
> preprocessor directives so you can more easily follow the logic in
> lengthy code segments?
> 
>   consider:
> 
>     #ifdef SNAFU
>     ... very long blah blah ...
>     #else
>     ... equally long woof woof ...
>     #endif
> 
>   if you're perusing the code, and you hit the "#else" or "#endif",
> it's almost impossible to tell what they correspond to, particularly
> if they're mixed in with even more nested directives.  so what's the
> best way to make this more readable?
> 
>   what about something like?
> 
>     #ifdef SNAFU
>     ...
>     #else /* !SNAFU */
>     ...
>     #endif /* !SNAFU */
> 
>   i contend that both of those new comments have value since, without
> them, you wouldn't know what either the "#else" or "#endif"
> represented.  but i'm willing to be disabused of that notion.
> 
>   thoughts?

Your example almost matches my preference/style, but there is no Linux
kernel "standard" for this AFAIK.

I would probably use /* SNAFU */ on the #endif line, so that it's
consistent with the case of no #else block, but I see the case for
using !SNAFU as well.

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: standard for documenting conditional preprocessor directives?

[Andre Haupt]

On Mon, Aug 27, 2007 at 10:55:09AM -0400, Robert P. J. Day wrote:
> On Mon, 27 Aug 2007, Andre Haupt wrote:
> 
> > On Mon, Aug 27, 2007 at 09:47:09AM -0400, Robert P. J. Day wrote:
> > >
> > >   is there an understood standard for documenting conditional
> > > preprocessor directives so you can more easily follow the logic in
> > > lengthy code segments?
> > >
> > >   consider:
> > >
> > >     #ifdef SNAFU
> > >     ... very long blah blah ...
> > >     #else
> > >     ... equally long woof woof ...
> > >     #endif
> > >
> > >   if you're perusing the code, and you hit the "#else" or "#endif",
> > > it's almost impossible to tell what they correspond to, particularly
> > > if they're mixed in with even more nested directives.  so what's the
> > > best way to make this more readable?
> > >
> > >   what about something like?
> > >
> > >     #ifdef SNAFU
> > >     ...
> > >     #else /* !SNAFU */
> > >     ...
> > >     #endif /* !SNAFU */
> >
> > I would make that latter
> > 	#endif /* SNAFU */
> > instead, because the #endif refers to the #ifdef and not to the #else
> > statement.
> 
> i thought of that but imagine that you're perusing code and you
> remember that you'd already seen:
> 
>   #ifdef SNAFU
> 
> sometime later, you run across:
> 
>   #endif /* SNAFU */
> 
> now you're not sure if that's a simple end to "SNAFU" or possibly the
> "#else" part that you missed during the perusal.  i'll grant you that
so your perusal was not done very thoroughly ;-)

No, seriously. I understand your point and you see me half convinced.
This is nothing i would fight to death for, though ;-)

regards,

Andre

Re: standard for documenting conditional preprocessor directives?

[Robert P. J. Day]

On Mon, 27 Aug 2007, Andre Haupt wrote:

> On Mon, Aug 27, 2007 at 10:55:09AM -0400, Robert P. J. Day wrote:

> > ... imagine that you're perusing code and you remember that you'd
> > already seen:
> >
> >   #ifdef SNAFU
> >
> > sometime later, you run across:
> >
> >   #endif /* SNAFU */
> >
> > now you're not sure if that's a simple end to "SNAFU" or possibly
> > the "#else" part that you missed during the perusal.  i'll grant
> > you that

> so your perusal was not done very thoroughly ;-)

i realize you're being humourous, but i can still address that point.
sometimes, you jump into the middle of a source file because you're
searching for something, and you're not sure if this code is  being
conditionally included.  if, just below it, you see

  #endif /* SNAFU */

you might *still* not be sure.  but if it says, instead

  #endif /* !SNAFU */

you're far more likely to understand it.

  in any event, i realize it might look awkward at first, but it seems
that this approach doesn't have any real drawbacks, and it has
measurable benefit.  and that's my theory. :-)

rday
-- 
====================================
Robert P. J. Day
Linux Consulting, Training and Annoying Kernel Pedantry
Waterloo, Ontario, CANADA

http://crashcourse.ca
====================================

Re: standard for documenting conditional preprocessor directives?

[Oleg Verych]

* 27-08-2007

Randy,

[]
> Your example almost matches my preference/style, but there is no Linux
> kernel "standard" for this AFAIK.

i've proposed all this some time ago, in order to simplify scripts, that
strip __KERNEL__ in headers, and get rid of `unifdef`. I'm sure you've
saw that in LKML. But you, as well known documentation supporter, didn't
wrote proposition in English. Now you are saying "no standard". Who other
than you can propose it?

[]
> ---
> ~Randy
> *** Remember to use Documentation/SubmitChecklist when testing your code ***
____
> -
> To unsubscribe from this list: send the line "unsubscribe kernel-janitors" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Argh!!..
____

Re: standard for documenting conditional preprocessor directives?

[Randy Dunlap]

On Tue, 4 Sep 2007 10:13:30 +0000 (UTC) Oleg Verych wrote:

> * 27-08-2007
> 
> Randy,
> 
> []
> > Your example almost matches my preference/style, but there is no Linux
> > kernel "standard" for this AFAIK.
> 
> i've proposed all this some time ago, in order to simplify scripts, that
> strip __KERNEL__ in headers, and get rid of `unifdef`. I'm sure you've
> saw that in LKML. But you, as well known documentation supporter, didn't
> wrote proposition in English. Now you are saying "no standard". Who other
> than you can propose it?

Anyone can.  I just don't see a need for this particular one.


> []
> > ---
> > ~Randy
> > *** Remember to use Documentation/SubmitChecklist when testing your code ***
> ____
> > -
> > To unsubscribe from this list: send the line "unsubscribe kernel-janitors" in
> > the body of a message to majordomo@vger.kernel.org
> > More majordomo info at  http://vger.kernel.org/majordomo-info.html
> 
> Argh!!..


What?  any why does your email interface not use or support
reply-to-all?


---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: standard for documenting conditional preprocessor directives?

[Oleg Verych]

* Tue, 4 Sep 2007 11:19:29 -0700
* Organization: YPO4
>
> On Tue, 4 Sep 2007 10:13:30 +0000 (UTC) Oleg Verych wrote:
>
>> * 27-08-2007
>> 
>> Randy,
>> 
>> []
>> > Your example almost matches my preference/style, but there is no Linux
>> > kernel "standard" for this AFAIK.

{1}

>> 
>> i've proposed all this some time ago, in order to simplify scripts, that
>> strip __KERNEL__ in headers, and get rid of `unifdef`. I'm sure you've
>> saw that in LKML. But you, as well known documentation supporter, didn't
>> wrote proposition in English. Now you are saying "no standard". Who other
>> than you can propose it?
>
> Anyone can.  I just don't see a need for this particular one.

IMHO you should say so at first turn in {1}. Never mind, then.

>> []
>> > ---
>> > ~Randy
>> > *** Remember to use Documentation/SubmitChecklist when testing your code ***
>> ____
>> > -
>> > To unsubscribe from this list: send the line "unsubscribe kernel-janitors" in
>> > the body of a message to majordomo@vger.kernel.org
>> > More majordomo info at  http://vger.kernel.org/majordomo-info.html
>> 
>> Argh!!..
>
>
> What?  any why does your email interface not use or support
> reply-to-all?

Sorry, i'm getting more and more used to reply to group, not to
mailing list. Kind of not-silly, network friendly, clean

"do not ever CC me, i'm reading what i need, when i have time."

> ---
> ~Randy
> *** Remember to use Documentation/SubmitChecklist when testing your code ***
> -
> To unsubscribe from this list: send the line "unsubscribe kernel-janitors" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
--
-o--=O`C
 #oo'L O
<___=E M