[C source] Inconsistent comments on preprocessor conditionals

[C source] Inconsistent comments on preprocessor conditionals

[Akib Azmain Turja]

[-- Attachment #1: Type: text/plain, Size: 926 bytes --]


In some parts of the C source, preprocessor conditionals are commented
like the following:

--8<---------------cut here---------------start------------->8---
#ifdef FOO
...
#else /* not FOO */
...
#endif /* FOO */
--8<---------------cut here---------------end--------------->8---

I became confused at the first glance.  But after seeing like the
following in some other part:

--8<---------------cut here---------------start------------->8---
#ifdef FOO
...
#else /* not FOO */
...
#endif /* not FOO */
--8<---------------cut here---------------end--------------->8---

I became even more confused.  Why it's inconsistent?  And what should I
do when adding new conditional blocks?  Should I follow the GNU coding
standards (the second one)?

-- 
Akib Azmain Turja

This message is signed by me with my GnuPG key.  It's fingerprint is:

    7001 8CE5 819F 17A3 BBA6  66AF E74F 0EFA 922A E7F5

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: [C source] Inconsistent comments on preprocessor conditionals

[Eli Zaretskii]

> From: Akib Azmain Turja <akib@disroot.org>
> Date: Fri, 08 Jul 2022 18:47:33 +0600
> 
> In some parts of the C source, preprocessor conditionals are commented
> like the following:
> 
> --8<---------------cut here---------------start------------->8---
> #ifdef FOO
> ...
> #else /* not FOO */
> ...
> #endif /* FOO */
> --8<---------------cut here---------------end--------------->8---
> 
> I became confused at the first glance.  But after seeing like the
> following in some other part:
> 
> --8<---------------cut here---------------start------------->8---
> #ifdef FOO
> ...
> #else /* not FOO */
> ...
> #endif /* not FOO */
> --8<---------------cut here---------------end--------------->8---
> 
> I became even more confused.  Why it's inconsistent?

You mean, the comment for the #endif line?  It doesn't really matter
how you comment that, because both comments tell the same: the
#ifdef'ed conditional block ends here.  The differences in this case
are purely stylistic.

> Should I follow the GNU coding standards (the second one)?

Yes, please.

Re: [C source] Inconsistent comments on preprocessor conditionals

[Phil Sainty]

On 2022-07-09 00:55, Eli Zaretskii wrote:
> You mean, the comment for the #endif line?  It doesn't really matter
> how you comment that, because both comments tell the same: the
> #ifdef'ed conditional block ends here.  The differences in this case
> are purely stylistic.

The "#endif /* not FOO */" version provides the extra information that
there *is* an "#else" clause -- which might be helpful if the clauses
are spaced very far apart.  If "#endif /* FOO */" is then consistently
used only for cases with no "#else", some code may be (very) slightly
easier for people to parse.

(As that was your recommended approach, this is nothing more than a
an observation supporting that preference.)

Re: [C source] Inconsistent comments on preprocessor conditionals

[Eli Zaretskii]

> Date: Sat, 09 Jul 2022 01:33:26 +1200
> From: Phil Sainty <psainty@orcon.net.nz>
> Cc: Akib Azmain Turja <akib@disroot.org>, emacs-devel@gnu.org
> 
> On 2022-07-09 00:55, Eli Zaretskii wrote:
> > You mean, the comment for the #endif line?  It doesn't really matter
> > how you comment that, because both comments tell the same: the
> > #ifdef'ed conditional block ends here.  The differences in this case
> > are purely stylistic.
> 
> The "#endif /* not FOO */" version provides the extra information that
> there *is* an "#else" clause

No, it doesn't, because the conditional could start with #ifndef
instead.

Re: [C source] Inconsistent comments on preprocessor conditionals

[Akib Azmain Turja]

[-- Attachment #1: Type: text/plain, Size: 1112 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Sat, 09 Jul 2022 01:33:26 +1200
>> From: Phil Sainty <psainty@orcon.net.nz>
>> Cc: Akib Azmain Turja <akib@disroot.org>, emacs-devel@gnu.org
>> 
>> On 2022-07-09 00:55, Eli Zaretskii wrote:
>> > You mean, the comment for the #endif line?  It doesn't really matter
>> > how you comment that, because both comments tell the same: the
>> > #ifdef'ed conditional block ends here.  The differences in this case
>> > are purely stylistic.
>> 
>> The "#endif /* not FOO */" version provides the extra information that
>> there *is* an "#else" clause
>
> No, it doesn't, because the conditional could start with #ifndef
> instead.

Then we can do like the following:

--8<---------------cut here---------------start------------->8---
#ifndef FOO
...
#else /* not !FOO */
...
#endif /* not !FOO */
--8<---------------cut here---------------end--------------->8---

Very confusing though.

-- 
Akib Azmain Turja

This message is signed by me with my GnuPG key.  It's fingerprint is:

    7001 8CE5 819F 17A3 BBA6  66AF E74F 0EFA 922A E7F5

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: [C source] Inconsistent comments on preprocessor conditionals

[Eli Zaretskii]

> From: Akib Azmain Turja <akib@disroot.org>
> Cc: emacs-devel@gnu.org
> Date: Fri, 08 Jul 2022 19:55:05 +0600
> 
> >> The "#endif /* not FOO */" version provides the extra information that
> >> there *is* an "#else" clause
> >
> > No, it doesn't, because the conditional could start with #ifndef
> > instead.
> 
> Then we can do like the following:
> 
> --8<---------------cut here---------------start------------->8---
> #ifndef FOO
> ...
> #else /* not !FOO */
> ...
> #endif /* not !FOO */
> --8<---------------cut here---------------end--------------->8---
> 
> Very confusing though.

Exactly.  Which is why we won't do that.

Re: [C source] Inconsistent comments on preprocessor conditionals

[Phil Sainty]

On 2022-07-09 01:55, Akib Azmain Turja wrote:
> #ifndef FOO
> #else /* not !FOO */
> #endif /* not !FOO */
> 
> Very confusing though.

It could be confusing to have an else clause with an
"if not" in the first place (that double-negative is
there regardless of whether it's commented that way
too); but of course Eli is right -- my logic doesn't
hold for that scenario.

Re: [C source] Inconsistent comments on preprocessor conditionals

[Sergey Organov]

Akib Azmain Turja <akib@disroot.org> writes:

> Eli Zaretskii <eliz@gnu.org> writes:
>
>>> Date: Sat, 09 Jul 2022 01:33:26 +1200
>>> From: Phil Sainty <psainty@orcon.net.nz>
>>> Cc: Akib Azmain Turja <akib@disroot.org>, emacs-devel@gnu.org
>>> 
>>> On 2022-07-09 00:55, Eli Zaretskii wrote:
>>> > You mean, the comment for the #endif line?  It doesn't really matter
>>> > how you comment that, because both comments tell the same: the
>>> > #ifdef'ed conditional block ends here.  The differences in this case
>>> > are purely stylistic.
>>> 
>>> The "#endif /* not FOO */" version provides the extra information that
>>> there *is* an "#else" clause
>>
>> No, it doesn't, because the conditional could start with #ifndef
>> instead.
>
> Then we can do like the following:
>
> #ifndef FOO
> ...
> #else /* not !FOO */
> ...
> #endif /* not !FOO */

It should then rather be something like:

#ifndef FOO
#else  /* not ndef FOO */
#endif /* not ndef FOO */

as there also could be:

#if !FOO
#else  /* not !FOO */
#endif /* not !FOO */

From that POV, the original should better be:

#ifdef FOO
#else  /* not def FOO */
#endif /* not def FOO */

to tell it from:

#if FOO
#else  /* not FOO */
#endif /* not FOO */

Just for mentioning, for myself I've adopted shorter style:

#ifdef FOO
#else  /*! def FOO */
#endif /*! def FOO */

where "/*!" reads like a specific single token clearly separate from the
#if condition, thus avoiding confusion.

-- 
Sergey Organov

Re: [C source] Inconsistent comments on preprocessor conditionals

[Stefan Monnier]

> The "#endif /* not FOO */" version provides the extra information that
> there *is* an "#else" clause -- which might be helpful if the clauses
> are spaced very far apart.  If "#endif /* FOO */" is then consistently
> used only for cases with no "#else", some code may be (very) slightly
> easier for people to parse.

FWIW, I personally never trust whether the comment is positive or
negative; instead the comment only tells me that it's the else/endif
that matches the condition that has to do with FOO (as opposed to some
other `#if` that tests something different), so the presence/absence of
`not` doesn't make much difference for me.  Maybe it's because of a lack
of a clear and religiously followed convention.

Also, those comments tend to get out of sync with the code, of course.

IOW, I'd rather not have those comments and let Emacs generate that info
dynamically, so it's always up-to-date and reliable.


        Stefan

Re: [C source] Inconsistent comments on preprocessor conditionals

[Akib Azmain Turja]

[-- Attachment #1: Type: text/plain, Size: 1509 bytes --]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> The "#endif /* not FOO */" version provides the extra information that
>> there *is* an "#else" clause -- which might be helpful if the clauses
>> are spaced very far apart.  If "#endif /* FOO */" is then consistently
>> used only for cases with no "#else", some code may be (very) slightly
>> easier for people to parse.
>
> FWIW, I personally never trust whether the comment is positive or
> negative; instead the comment only tells me that it's the else/endif
> that matches the condition that has to do with FOO (as opposed to some
> other `#if` that tests something different), so the presence/absence of
> `not` doesn't make much difference for me.  Maybe it's because of a lack
> of a clear and religiously followed convention.
>
> Also, those comments tend to get out of sync with the code, of course.
>
> IOW, I'd rather not have those comments and let Emacs generate that info
> dynamically, so it's always up-to-date and reliable.
>
>
>         Stefan
>

Yes, comments are actually hints, and they can get out of sync.  But I
usually study programs relatively much new, which is written once and
the working parts are never touched again.  Comments there are usually
up to date.  But for the almost half a century old source code of Emacs,
this is not true.

-- 
Akib Azmain Turja

This message is signed by me with my GnuPG key.  It's fingerprint is:

    7001 8CE5 819F 17A3 BBA6  66AF E74F 0EFA 922A E7F5

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: [C source] Inconsistent comments on preprocessor conditionals

[Po Lu]

Akib Azmain Turja <akib@disroot.org> writes:

> In some parts of the C source, preprocessor conditionals are commented
> like the following:
>
> #ifdef FOO
> ...
> #else /* not FOO */
> ...
> #endif /* FOO */
>
>
> I became confused at the first glance.  But after seeing like the
> following in some other part:
>
> #ifdef FOO
> ...
> #else /* not FOO */
> ...
> #endif /* not FOO */
>
> I became even more confused.  Why it's inconsistent?  And what should I
> do when adding new conditional blocks?  Should I follow the GNU coding
> standards (the second one)?

They are optional, I think.  I personally only write such comments when
the code inside the conditional extends so long that what is inside the
conditional is not immediately obvious.

Re: [C source] Inconsistent comments on preprocessor conditionals

[Alan Mackenzie]

Hello, Akib

On Fri, Jul 08, 2022 at 18:47:33 +0600, Akib Azmain Turja wrote:

> In some parts of the C source, preprocessor conditionals are commented
> like the following:

> --8<---------------cut here---------------start------------->8---
> #ifdef FOO
> ...
> #else /* not FOO */
> ...
> #endif /* FOO */
> --8<---------------cut here---------------end--------------->8---

> I became confused at the first glance.  But after seeing like the
> following in some other part:

> --8<---------------cut here---------------start------------->8---
> #ifdef FOO
> ...
> #else /* not FOO */
> ...
> #endif /* not FOO */
> --8<---------------cut here---------------end--------------->8---

> I became even more confused.  Why it's inconsistent?  And what should I
> do when adding new conditional blocks?  Should I follow the GNU coding
> standards (the second one)?

Just as an aside, be aware (if you're not already) that you can navigate
the preprocessor commands with the key sequences C-c C-n, C-c C-p, and
C-c C-u.

> -- 
> Akib Azmain Turja

> This message is signed by me with my GnuPG key.  It's fingerprint is:

>     7001 8CE5 819F 17A3 BBA6  66AF E74F 0EFA 922A E7F5

-- 
Alan Mackenzie (Nuremberg, Germany).