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

This is a multi-part message in MIME format...

------------=_1090177434-12871-2
Content-Type: text/plain; charset="utf-8"


<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


------------=_1090177434-12871-2
Content-Type: text/x-patch; charset="utf-8"; name="inline-2.diff"
Content-Disposition: inline; filename="inline-2.diff"
Content-Transfer-Encoding: 7bit

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
 ===========================================================================
 

------------=_1090177434-12871-2--