docs/docbook/devdoc/CodingSuggestions.xml

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