[Freeciv-Dev] (PR#9117) guidelines for macros and inline functions

["Jason Short" <jdorje@xxxxxxxxxxxxxxxxxxxxx>]

<URL: http://rt.freeciv.org/Ticket/Display.html?id=9117 >

We've had some discussions about what code should be macros and what 
should be inline.  Nobody agrees, of course.

We've also had problems with "break" in iterator macros.

This patch adds guidelines to doc/HACKING on the use of macros and 
inline functions.  Of course nobody will agree with them.  They're 
intended to be a compromise between fixing some broken behavior (the 
first three rules) and keeping the status quo (the last three rules).

jason

Index: doc/HACKING
===================================================================
RCS file: /home/freeciv/CVS/freeciv/doc/HACKING,v
retrieving revision 1.19
diff -u -r1.19 HACKING
--- doc/HACKING 16 May 2004 19:07:35 -0000      1.19
+++ doc/HACKING 26 Jun 2004 22:14:17 -0000
@@ -984,6 +984,39 @@
 
 
 ===========================================================================
+Macros and inline functions
+===========================================================================
+
+For a long time Freeciv had no inline functions, only macros.  With the
+use of other C99 features and some new requirements by the code, this has
+changed.  Now both macros and inline functions are used.
+
+This causes problems because one coder may prefer to use a macro while
+another prefers an inline function.  Of course there was always some
+discretion to the author about whether to use a function or a macro; all
+we've done is add even more choices.
+
+Therefore the following guidelines should be followed:
+
+- Functions should only be inlined or macroed when doing so makes a
+  measurable impact on speed.
+
+- Macros that take function-like parameters should evaluate each parameter
+  exactly once.  Any macro that doesn't follow this convention should be
+  named in all upper-case letters as a MACRO.
+
+- Iterator macros should respect "break".
+
+- Macros are preferred to inline functions, but inline functions are
+  better than MACROS.
+
+- Functions or macros that are currently in one form do not have to be
+  changed to the other form.
+
+Note that many existing macros do not follow these guidelines.
+
+
+===========================================================================
 Style Guide
 ===========================================================================