Complete.Org: Mailing Lists: Archives: freeciv-data: July 2004:
[freeciv-data] (PR#9117) Documentation: guidelines for macros and inline

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

[Top] [All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index] [Thread Index]
Cc: freeciv-data@xxxxxxxxxxx
Subject: [freeciv-data] (PR#9117) Documentation: guidelines for macros and inline functions
From: "Jason Short" <jdorje@xxxxxxxxxxxxxxxxxxxxx>
Date: Sun, 18 Jul 2004 12:03:54 -0700
Reply-to: freeciv-data@xxxxxxxxxxx

<URL: >

> [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?


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

[Prev in Thread] Current Thread [Next in Thread]
  • [freeciv-data] (PR#9117) Documentation: guidelines for macros and inline functions, Jason Short <=