#define<TAB> in share/misc/style [was: CVS commit: src/share/misc]

[John Hawkinson <jhawk%MIT.EDU@localhost>]

I'm moving this discussion to tech-misc%netbsd.org@localhost, where I think it's
more appropriate; I hadn't expected it to be quite as "popular."

BACKGROUND

On Sunday, I committed this change to share/misc/style (rev 1.21):

Log Message: 
Clarify that macros should be #define<TAB>; it's important to
specify this in the actual document, just not in the cvs logs
(cf. rev 1.15).

 /*
  * Macros are capitalized, parenthesized, and should avoid side-effects.
+ * Use one TAB between #define and the macro name; spacing after the macro
+ * name may be any whitespace, as appropriate.
  * If they are an inline expansion of a function, the function is defined
  * all in lowercase, the macro has the same name all in uppercase.
  * If the macro is an expression, wrap the expression in parenthesis.

We then had a discussion on source-changes. Izumi asked if there
was concensus on the change, and suggested 1.15 was really trying to
say "use the same style in the same file," not "always use a TAB."

Klaus observed that a number of files had recently transitioned from
#define<SP> to #define<TAB>, accompanied by a reference to KNF. If
anything, I guess this just shows there is confusion on the topic.

Luke points out his preference for <TAB>, and though he committed 1.15,
he's not the sole arbiter of this kind of thing.

Lastly, Izumi suggests:
> Some developers requested me to use #define<space>.
> Anyway, I don't think we have any consensus so
> the similar statement in ANSI declaration section is proper:
> 
>  * Use your discretion on indenting between the return type and the name, and
>  * how to wrap a prototype too long for a single line.  In the latter case,
>  * lining up under the initial left parenthesis may be more readable.
>  * In any case, consistency is important!


DISCUSSION

I went through all commits since 22 Nov featuring 'knf' in the commit
log (well, the first file of each since my script was broken), and I
see very few cases of this changing, so I'm not sure what Klaus was
referring to.

src/sys/netsmb/smb_trantcp.h 1.3 broke it with an unrelated change,
though, which is vaguely ironic, I think:

---cut
+/*
+ * Timeouts used for send/receive. XXX Sysctl this?
  */
-#define^INB_SNDQ^I^I(10 * 1024)
-#define^INB_RCVQ^I^I(20 * 1024)
+#define NB_SNDTIMEO^I(5 * hz)
+#define NB_RCVTIMEO^I(5 * hz)
---cut

If anyone cares, OpenBSD's style(9) is silent on this topic.
FreeBSD's, however, states [EMPHASIS mine]:

---cut
The names of ``unsafe'' macros (ones that have side effects), and the
names of macros for manifest constants, are all in uppercase.  The expan-
sions of expression-like macros are either a single token or have outer
parentheses.  PUT A SINGLE TAB CHARACTER BETWEEN THE #DEFINE AND THE
MACRO NAME.  If a macro is an inline expansion of a function, the func-
tion name is all in lowercase and the macro has the same name all in up-
percase.  Right-justify the backslashes; it makes it easier to read.  If
the macro encapsulates a compound statement, enclose it in a do loop, so
that it can safely be used in if statements.  Any final statement-termi-
nating semicolon should be supplied by the macro invocation rather than
the macro, to make parsing easier for pretty-printers and editors.

#define MACRO(x, y) do {                                                \
        variable = (x) + (y);                                           \
        (y) += 2;                                                       \
} while (0)
---cut

This changelog was:

---cut
Revision 1.31 Thu Dec 16 10:02:20 1999 UTC (3 years, 2 months ago) by obrien
Changes since 1.30: +7 -4 lines

* State in words that "#define^IMACRO" is proper, as it is hard to tell
  from the example.
* Embelish the usage() example to show how uppercase options are sorted.

Taken from previous bdelinting.
---cut

Certainly, I thinks wise to be consistent with the other BSDs if it
doesn't cost us anything ("at least, where [we/I] agree with them").

It's not terribly clear to me how we arise at concensus in this
regard. It's the kind of thing that should probably not be a complete
free-for-all. I'm not comfortable assuming concensus from silence.

In any case, we should not leave it ambiguous.
It seems to me the two options are my text (or variation thereof),
or text such as:

 /*
  * Macros are capitalized, parenthesized, and should avoid side-effects.
+ * Spacing before and after the macro name may be any whitespace, though
+ * use of TABs should be consistent throughout the file.
  * If they are an inline expansion of a function, the function is defined
  * all in lowercase, the macro has the same name all in uppercase.
  * If the macro is an expression, wrap the expression in parenthesis.

Are there other opinions or responses to my analysis?

--jhawk