source3/CodingSuggestions

   1 /**
   2
   3 @page CodingSuggestions Coding suggestions
   4
   5 So you want to add code to Samba ...
   6
   7 One of the daunting tasks facing a programmer attempting to write code for
   8 Samba is understanding the various coding conventions used by those most
   9 active in the project.  These conventions were mostly unwritten and helped
  10 improve either the portability, stability or consistency of the code. This
  11 document will attempt to document a few of the more important coding
  12 practices used at this time on the Samba project.  The coding practices are
  13 expected to change slightly over time, and even to grow as more is learned
  14 about obscure portability considerations.  Two existing documents
  15 samba/source/internals.doc and samba/source/architecture.doc provide
  16 additional information.
  17
  18 The loosely related question of coding style is very personal and this
  19 document does not attempt to address that subject, except to say that I
  20 have observed that eight character tabs seem to be preferred in Samba
  21 source.  If you are interested in the topic of coding style, two oft-quoted
  22 documents are:
  23
  24    http://lxr.linux.no/source/Documentation/CodingStyle
  25    http://www.fsf.org/prep/standards_toc.html
  26
  27 but note that coding style in Samba varies due to the many different
  28 programmers who have contributed.
  29
  30 Following are some considerations you should use when adding new code to
  31 Samba.  First and foremost remember that:
  32
  33 Portability is a primary consideration in adding function, as is network
  34 compatability with de facto, existing, real world CIFS/SMB implementations.
  35 There are lots of platforms that Samba builds on so use caution when adding
  36 a call to a library function that is not invoked in existing Samba code.
  37 Also note that there are many quite different SMB/CIFS clients that Samba
  38 tries to support, not all of which follow the SNIA CIFS Technical Reference
  39 (or the earlier Microsoft reference documents or the X/Open book on the SMB
  40 Standard) perfectly.
  41
  42 Here are some other suggestions:
  43
  44 1) use d_printf instead of printf for display text
  45         reason: enable auto-substitution of translated language text
  46
  47 2) use SAFE_FREE instead of free
  48         reason: reduce traps due to null pointers
  49
  50 3) don't use bzero use memset, or ZERO_STRUCT and ZERO_STRUCTP macros
  51         reason: not POSIX
  52
  53 4) don't use strcpy and strlen (use safe_* equivalents)
  54         reason: to avoid traps due to buffer overruns
  55
  56 5) don't use getopt_long, use popt functions instead
  57         reason: portability
  58
  59 6) explicitly add const qualifiers on parm passing in functions where parm
  60    is input only (somewhat controversial but const can be #defined away)
  61
  62 7) when passing a va_list as an arg, or assigning one to another
  63    please use the VA_COPY() macro
  64         reason: on some platforms, va_list is a struct that must be
  65                 initialized in each function...can SEGV if you don't.
  66
  67 8) discourage use of threads
  68         reason: portability (also see architecture.doc)
  69
  70 9) don't explicitly include new header files in C files - new h files
  71    should be included by adding them once to includes.h
  72         reason: consistency
  73
  74 10) don't explicitly extern functions (they are autogenerated by
  75     "make proto" into proto.h)
  76         reason: consistency
  77
  78 11) use endian safe macros when unpacking SMBs (see byteorder.h and
  79     internals.doc)
  80         reason: not everyone uses Intel
  81
  82 12) Note Unicode implications of charset handling (see internals.doc).  See
  83     pull_*  and push_* and convert_string functions.
  84         reason: Internationalization
  85
  86 13) Don't assume English only
  87         reason: See above
  88
  89 14) Try to avoid using in/out parameters (functions that return data which
  90     overwrites input parameters)
  91         reason: Can cause stability problems
  92
  93 15) Ensure copyright notices are correct, don't append Tridge's name to code
  94     that he didn't write.  If you did not write the code, make sure that it
  95     can coexist with the rest of the Samba GPLed code.
  96
  97 16) Consider usage of DATA_BLOBs for length specified byte-data.
  98         reason: stability
  99
 100 17) Take advantage of tdbs for database like function
 101         reason: consistency
 102
 103 18) Don't access the SAM_ACCOUNT structure directly, they should be accessed
 104     via pdb_get...() and pdb_set...() functions.
 105         reason: stability, consistency
 106
 107 19) Don't check a password directly against the passdb, always use the
 108     check_password() interface.
 109         reason: long term pluggability
 110
 111 20) Try to use asprintf rather than pstrings and fstrings where possible
 112
 113 21) Use normal C comments / * instead of C++ comments // like
 114     this.  Although the C++ comment format is part of the C99
 115     standard, some older vendor C compilers do not accept it.
 116
 117 22) Try to write documentation for API functions and structures
 118     explaining the point of the code, the way it should be used, and
 119     any special conditions or results.  Mark these with a double-star
 120     comment start / ** so that they can be picked up by Doxygen, as in
 121     this file.
 122
 123 23) Keep the scope narrow. This means making functions/variables
 124     static whenever possible. We don't want our namespace
 125     polluted. Each module should have a minimal number of externally
 126     visible functions or variables.
 127
 128 24) Use function pointers to keep knowledge about particular pieces of
 129     code isolated in one place. We don't want a particular piece of
 130     functionality to be spread out across lots of places - that makes
 131     for fragile, hand to maintain code. Instead, design an interface
 132     and use tables containing function pointers to implement specific
 133     functionality. This is particularly important for command
 134     interpreters.
 135
 136 25) Think carefully about what it will be like for someone else to add
 137     to and maintain your code. If it would be hard for someone else to
 138     maintain then do it another way.
 139
 140 The suggestions above are simply that, suggestions, but the information may
 141 help in reducing the routine rework done on new code.  The preceeding list
 142 is expected to change routinely as new support routines and macros are
 143 added.
 144
 145 Written by Steve French, with contributions from Simo Sorce, Andrew
 146 Bartlett, Tim Potter and Martin Pool.
 147
 148 **/