Unused bits in defines and standardized define notation.

In https://github.com/Perl/perl5/pull/19120#issuecomment-1436073722 Dave M
complained about a change I had made as part of that PR (#19120), where I
created a placeholder define to represent an unused bit in a sequence of
flag bits in our defines.

The basic issue is how to list that a bit isnt used when we have many bits
defined, and at least to me, how we can use automation to keep them well
formatted, show the flag bit different ways, etc.

The patch originally was from Paul where he wanted to change defines that
looked like this:

#define SV_COW_SHARED_HASH_KEYS 512

to look like this:

#define SV_COW_SHARED_HASH_KEYS (1 << 9)

Many folks agreed this would be helpful but other folks complained they
find it helpful to see the decimal version as well, and others commented it
is handy to see the hex value as well.  The patch was stalled so I took a
moment to use a one liner to format it as this:

#define SV_COW_SHARED_HASH_KEYS (1 << 9) /* 0x0200 - 512 */

To make that script easier to write I needed to deal with the gap between 4
and 16 (eg bit 3, decimal value 8), see if you can notice there is a gap in
the original version of the file.  The simplest solution was to add a
placeholder define for the gap:

#define SV_FLAG_BIT3_UNUSED (1 << 3) /* 0x0008 - 8 */

Which to me is pretty easy and clean. Someone wanting  a bit can look for
UNUSED, and rename it. But in the comment above Dave M expressed that he
does not favour this style. That is fine, I respect him and his opinion on
such things hugely, so I want to try to find something that makes him and
me happy.  But to me this isn't so simple a decision. I find gaps in such
sequences confusing. It leaves much open to interpretation. He finds the
define I added confusing for equally legitimate reasons.   Making this more
difficult is that in C you cant nest comments. So we cant just say, stick a
comment around the define bit to addres some of his concerns.  And because
I didnt think of it, when I added the comments I didnt leave enough room to
comment out just the define.

So I would like to find a compromise that makes him and me and as many
people as possible happy about what we do, and establish a clear convention
on what we do with cases like this. In that end I have created 4 prs:

https://github.com/Perl/perl5/pull/20830
https://github.com/Perl/perl5/pull/20831
https://github.com/Perl/perl5/pull/20832
https://github.com/Perl/perl5/pull/20833

each with a slightly different variant of what we could do to deal with
this kind of thing. Id appreciate feedback from folks as to what they
prefer, especially you Dave.

The one I prefer is https://github.com/Perl/perl5/pull/20833

This is a little thing, but it does matter. Being able to write tools that
fix up things like this is really helpful, it avoids errors, and allows us
to ensure consistency, and this is not the only place where we have this
issue. There are others, including some where I have done something similar
to the patch that Dave doesn't like.   For instance we have some defines
where the definition is in hex with no decimal or power-of-two
representation, and where there are gaps, and where the number of hex
digits in the various different defines differs. This kind of thing bothers
my eyes, and makes me wondering about bugs unnecessarily. Getting
consistency of formatting IMO is helpful.

So can we find a compromise that we the majority of us can live with? I am
hoping we can.

cheers,
Yves



cheers,
Yves
-- 
perl -Mre=debug -e "/just|another|perl|hacker/"

• Unused bits in defines and standardized define notation. by demerphq
• Re: Unused bits in defines and standardized define notation. by Dave Mitchell
• Re: Unused bits in defines and standardized define notation. by demerphq