[freeciv-data] (PR#9117) Documentation: guidelines for macros and inline functions

["Jason Short" <jdorje@xxxxxxxxxxxxxxxxxxxxx>]

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

> [jdorje - Sat Jun 26 22:19:18 2004]:

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

This patch has some changes based on what other people complained about.
 Can everyone live with this?

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 18 Jul 2004 19:02:01 -0000
@@ -984,6 +984,40 @@
 
 
 ===========================================================================
+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 put into header files when doing so makes a
+  measurable impact on speed.  Functions should not be turned into macros or
+  inlined unless there is a reason to do so.
+
+- 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".
+
+- In header files 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
 ===========================================================================