Re: PATCH, RFC: 2.6 Documentation/Codingstyle

[viro@parcelfarce.linux.theplanet.co.uk]

On Fri, Feb 13, 2004 at 06:15:10AM +0800, Michael Frank wrote:
> +		Chapter : Macros
> +
> +Macros defining constants are capitalized.
> +
> +#define CONSTANT 0x12345
> +
> +CAPITALIZED macro names are appreciated but macros resembling functions
> +may be named in lower case.
> +
> +Macros with multiple statements should be enclosed in a do - while block.
> +
> +#define macrofun(a,b,c) 		\
> +do {					\
> +	if (a == 5)			\
> +		do_this(b,c);		\
> +					\
> +} while (0)
> +
> +Macros defining expressions must enclose the expression in parenthesis
> +to reduce sideeffects.
> +
> +#define CONSTEXP (CONSTANT | 3)
> +#define MACWEXP(a,b) ((a) + (b))

Generally, enum and inline functions are preferable to the above.

Things to avoid when doing macros:

	1) macros that affect control flow:

#define FOO(x) do {if (blah(x) < 0) return -EBUGGERED;} while(0)

is _not_ a good idea.  It looks like a function call; don't break the internal
parsers of those who will read the code.

	2) macros that depend on having a local variable with magic name:

#define FOO(val) bar(index, val)

might look like a good thing, but it's confusing as hell when one reads the
code and it's prone to breakage from seemingly innocent changes.

	3) macros with arguments that are used as l-values: FOO(x) = y; will
bite you if somebody e.g. turns FOO into inlined function.