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