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 8) discourage use of threads
  63         reason: portability (also see architecture.doc)
  64
  65 9) don't explicitly include new header files in C files - new h files
  66    should be included by adding them once to includes.h
  67         reason: consistency
  68
  69 10) don't explicitly extern functions (they are autogenerated by
  70     "make proto" into proto.h)
  71         reason: consistency
  72
  73 11) use endian safe macros when unpacking SMBs (see byteorder.h and
  74     internals.doc)
  75         reason: not everyone uses Intel
  76
  77 12) Note Unicode implications of charset handling (see internals.doc).  See
  78     pull_*  and push_* and convert_string functions.
  79         reason: Internationalization
  80
  81 13) Don't assume English only
  82         reason: See above
  83
  84 14) Try to avoid using in/out parameters (functions that return data which
  85     overwrites input parameters)
  86         reason: Can cause stability problems
  87
  88 15) Ensure copyright notices are correct, don't append Tridge's name to code
  89     that he didn't write.  If you did not write the code, make sure that it
  90     can coexist with the rest of the Samba GPLed code.
  91
  92 16) Consider usage of DATA_BLOBs for length specified byte-data.
  93         reason: stability
  94
  95 17) Take advantage of tdbs for database like function
  96         reason: consistency
  97
  98 18) Don't access the SAM_ACCOUNT structure directly, they should be accessed
  99     via pdb_get...() and pdb_set...() functions.
 100         reason: stability, consistency
 101
 102 19) Don't check a password directly against the passdb, always use the
 103     check_password() interface.
 104         reason: long term pluggability
 105
 106 20) Try to use asprintf rather than pstrings and fstrings where possible
 107
 108 21) Use normal C comments / * instead of C++ comments // like
 109     this.  Although the C++ comment format is part of the C99
 110     standard, some older vendor C compilers do not accept it.
 111
 112 22) Try to write documentation for API functions and structures
 113     explaining the point of the code, the way it should be used, and
 114     any special conditions or results.  Mark these with a double-star
 115     comment start / ** so that they can be picked up by Doxygen, as in
 116     this file.
 117
 118 23) Keep the scope narrow. This means making functions/variables
 119     static whenever possible. We don't want our namespace
 120     polluted. Each module should have a minimal number of externally
 121     visible functions or variables.
 122
 123 24) Use function pointers to keep knowledge about particular pieces of
 124     code isolated in one place. We don't want a particular piece of
 125     functionality to be spread out across lots of places - that makes
 126     for fragile, hand to maintain code. Instead, design an interface
 127     and use tables containing function pointers to implement specific
 128     functionality. This is particularly important for command
 129     interpreters.
 130
 131 25) Think carefully about what it will be like for someone else to add
 132     to and maintain your code. If it would be hard for someone else to
 133     maintain then do it another way.
 134
 135 The suggestions above are simply that, suggestions, but the information may
 136 help in reducing the routine rework done on new code.  The preceeding list
 137 is expected to change routinely as new support routines and macros are
 138 added.
 139
 140 Written by Steve French, with contributions from Simo Sorce, Andrew
 141 Bartlett, Tim Potter and Martin Pool.
 142
 143 **/