unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
* [C source] Inconsistent comments on preprocessor conditionals
@ 2022-07-08 12:47 Akib Azmain Turja
  2022-07-08 12:55 ` Eli Zaretskii
                   ` (2 more replies)
  0 siblings, 3 replies; 12+ messages in thread
From: Akib Azmain Turja @ 2022-07-08 12:47 UTC (permalink / raw)
  To: emacs-devel

[-- 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 --]

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [C source] Inconsistent comments on preprocessor conditionals
  2022-07-08 12:47 [C source] Inconsistent comments on preprocessor conditionals Akib Azmain Turja
@ 2022-07-08 12:55 ` Eli Zaretskii
  2022-07-08 13:33   ` Phil Sainty
  2022-07-08 12:57 ` Po Lu
  2022-07-08 13:47 ` Alan Mackenzie
  2 siblings, 1 reply; 12+ messages in thread
From: Eli Zaretskii @ 2022-07-08 12:55 UTC (permalink / raw)
  To: Akib Azmain Turja; +Cc: emacs-devel

> 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.



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [C source] Inconsistent comments on preprocessor conditionals
  2022-07-08 12:47 [C source] Inconsistent comments on preprocessor conditionals Akib Azmain Turja
  2022-07-08 12:55 ` Eli Zaretskii
@ 2022-07-08 12:57 ` Po Lu
  2022-07-08 13:47 ` Alan Mackenzie
  2 siblings, 0 replies; 12+ messages in thread
From: Po Lu @ 2022-07-08 12:57 UTC (permalink / raw)
  To: Akib Azmain Turja; +Cc: emacs-devel

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.



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [C source] Inconsistent comments on preprocessor conditionals
  2022-07-08 12:55 ` Eli Zaretskii
@ 2022-07-08 13:33   ` Phil Sainty
  2022-07-08 13:37     ` Eli Zaretskii
  2022-07-08 19:54     ` Stefan Monnier
  0 siblings, 2 replies; 12+ messages in thread
From: Phil Sainty @ 2022-07-08 13:33 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: Akib Azmain Turja, emacs-devel

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.)




^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [C source] Inconsistent comments on preprocessor conditionals
  2022-07-08 13:33   ` Phil Sainty
@ 2022-07-08 13:37     ` Eli Zaretskii
  2022-07-08 13:55       ` Akib Azmain Turja
  2022-07-08 19:54     ` Stefan Monnier
  1 sibling, 1 reply; 12+ messages in thread
From: Eli Zaretskii @ 2022-07-08 13:37 UTC (permalink / raw)
  To: Phil Sainty; +Cc: akib, emacs-devel

> 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.



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [C source] Inconsistent comments on preprocessor conditionals
  2022-07-08 12:47 [C source] Inconsistent comments on preprocessor conditionals Akib Azmain Turja
  2022-07-08 12:55 ` Eli Zaretskii
  2022-07-08 12:57 ` Po Lu
@ 2022-07-08 13:47 ` Alan Mackenzie
  2 siblings, 0 replies; 12+ messages in thread
From: Alan Mackenzie @ 2022-07-08 13:47 UTC (permalink / raw)
  To: Akib Azmain Turja; +Cc: emacs-devel

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).



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [C source] Inconsistent comments on preprocessor conditionals
  2022-07-08 13:37     ` Eli Zaretskii
@ 2022-07-08 13:55       ` Akib Azmain Turja
  2022-07-08 14:01         ` Eli Zaretskii
                           ` (2 more replies)
  0 siblings, 3 replies; 12+ messages in thread
From: Akib Azmain Turja @ 2022-07-08 13:55 UTC (permalink / raw)
  To: Eli Zaretskii, Phil Sainty; +Cc: emacs-devel

[-- 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 --]

^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [C source] Inconsistent comments on preprocessor conditionals
  2022-07-08 13:55       ` Akib Azmain Turja
@ 2022-07-08 14:01         ` Eli Zaretskii
  2022-07-08 14:21         ` Phil Sainty
  2022-07-08 16:28         ` Sergey Organov
  2 siblings, 0 replies; 12+ messages in thread
From: Eli Zaretskii @ 2022-07-08 14:01 UTC (permalink / raw)
  To: Akib Azmain Turja; +Cc: psainty, emacs-devel

> 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.



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [C source] Inconsistent comments on preprocessor conditionals
  2022-07-08 13:55       ` Akib Azmain Turja
  2022-07-08 14:01         ` Eli Zaretskii
@ 2022-07-08 14:21         ` Phil Sainty
  2022-07-08 16:28         ` Sergey Organov
  2 siblings, 0 replies; 12+ messages in thread
From: Phil Sainty @ 2022-07-08 14:21 UTC (permalink / raw)
  To: Akib Azmain Turja; +Cc: Eli Zaretskii, emacs-devel

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.




^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [C source] Inconsistent comments on preprocessor conditionals
  2022-07-08 13:55       ` Akib Azmain Turja
  2022-07-08 14:01         ` Eli Zaretskii
  2022-07-08 14:21         ` Phil Sainty
@ 2022-07-08 16:28         ` Sergey Organov
  2 siblings, 0 replies; 12+ messages in thread
From: Sergey Organov @ 2022-07-08 16:28 UTC (permalink / raw)
  To: Akib Azmain Turja; +Cc: Eli Zaretskii, Phil Sainty, emacs-devel

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



^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [C source] Inconsistent comments on preprocessor conditionals
  2022-07-08 13:33   ` Phil Sainty
  2022-07-08 13:37     ` Eli Zaretskii
@ 2022-07-08 19:54     ` Stefan Monnier
  2022-07-11 12:42       ` Akib Azmain Turja
  1 sibling, 1 reply; 12+ messages in thread
From: Stefan Monnier @ 2022-07-08 19:54 UTC (permalink / raw)
  To: Phil Sainty; +Cc: Eli Zaretskii, Akib Azmain Turja, emacs-devel

> 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




^ permalink raw reply	[flat|nested] 12+ messages in thread

* Re: [C source] Inconsistent comments on preprocessor conditionals
  2022-07-08 19:54     ` Stefan Monnier
@ 2022-07-11 12:42       ` Akib Azmain Turja
  0 siblings, 0 replies; 12+ messages in thread
From: Akib Azmain Turja @ 2022-07-11 12:42 UTC (permalink / raw)
  To: Stefan Monnier, Phil Sainty; +Cc: Eli Zaretskii, emacs-devel

[-- 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 --]

^ permalink raw reply	[flat|nested] 12+ messages in thread

end of thread, other threads:[~2022-07-11 12:42 UTC | newest]

Thread overview: 12+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-07-08 12:47 [C source] Inconsistent comments on preprocessor conditionals Akib Azmain Turja
2022-07-08 12:55 ` Eli Zaretskii
2022-07-08 13:33   ` Phil Sainty
2022-07-08 13:37     ` Eli Zaretskii
2022-07-08 13:55       ` Akib Azmain Turja
2022-07-08 14:01         ` Eli Zaretskii
2022-07-08 14:21         ` Phil Sainty
2022-07-08 16:28         ` Sergey Organov
2022-07-08 19:54     ` Stefan Monnier
2022-07-11 12:42       ` Akib Azmain Turja
2022-07-08 12:57 ` Po Lu
2022-07-08 13:47 ` Alan Mackenzie

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).