git.sur5r.net Git - openldap/blob - CODING.RULES

   1 Coding rules and hints for OpenLDAP developers.
   2 ===============================================
   3
   4
   5 Please add to this file when new points come up.
   6
   7
   8 C source
   9 --------
  10
  11 We require ISO C support, or at least prototypes, to *build* OpenLDAP,
  12 but .h files that will be installed should support K&R C.
  13
  14 .c files in the OpenLDAP source tree MUST #include "portable.h" before
  15 any other include file, even system includes.  portable.h may control
  16 aspects of system includes, such as whether or not thread-safe library
  17 functions are used.  (Separate applications can't use portable.h, since
  18 it is not installed.  They can use ldap_features.h, though.)
  19
  20 .h files that are NOT INSTALLED may depend on features from portable.h.
  21 .h files that *are* installed (from include/) should not depend on it.
  22
  23 Avoid unnecessary changes, like reindenting code, even if that leaves
  24 the code a little more ugly.  Unnecessary changes make it harder to
  25 maintain and merge different CVS branches of the source.
  26
  27 Use feature-specific #if tests (like #ifdef HAVE_LWP) which configure
  28 can figure out, not system-specific test (like #ifdef __SunOS_5_6).
  29
  30 When available, use include files from ldap/include/ac/ to get system
  31 features or functions.  The <ac/xxx.h> files try to fix crippled system
  32 includes, and to hide #ifdef messes that portable programs need in order
  33 to find a feature.  Note that a file <ac/xxx.h> is not necessarily
  34 designed to be equivalent to standard C's <xxx.h> file.
  35
  36 Nonstatic function and variable definitions in .c files should be
  37 preceded by their declarations in .h files.  Avoid implicit function
  38 declarations.  Avoid external declarations in .c files.
  39
  40 When a function returns non-void, it should return a meaningful value.
  41 Avoid implicit int.
  42
  43
  44
  45 CVS updating
  46 ------------
  47
  48 <URL:http://www.openldap.org/repo.html> describes how to check out
  49 -stable.  To get the -devel (HEAD) branch, omit `-r OPENLDAP_STABLE'.
  50
  51 Core members should subscribe to the private -core mailinglist and
  52 coordinate activities there.
  53
  54 Do not commit a patch, however small, without at least testing that it
  55 compiles.
  56
  57 In general, a patch/bugfix should be applied to -devel and tested.
  58 When the patch is considered stable, then it can be merged into -stable.
  59 Same goes for other release engineering branches (like
  60 OPENLDAP_REL_ENG_1_1).  (-stable is rel eng 1.0).
  61 Specific procjects may get their own branches, to be merged later.
  62
  63 Log messages: Just describe the change and reason.  CVS adds your name,
  64 date, etc.
  65
  66
  67 Various tips and hints
  68 ----------------------
  69
  70 How to correct a CVS log message:
  71 Commit the unchanged files again with the `-f' flag and with a log
  72 message stating how the previous log was in error:
  73         cvs commit -f cldap.c os-ip.c
  74 Preferably, prepend a line something like this to the message:
  75 "Forced commit to correct previous log, files were not changed."
  76
  77 Modify ldapconfig.h instead of ldapconfig.h.edit.  Then `cvs commit'
  78 from the include directory won't accidentally commit your private
  79 ldapconfig.h.edit.