diff options
Diffstat (limited to 'docs/devel/CodingSuggestions.xml')
| -rw-r--r-- | docs/devel/CodingSuggestions.xml | 237 |
1 files changed, 237 insertions, 0 deletions
diff --git a/docs/devel/CodingSuggestions.xml b/docs/devel/CodingSuggestions.xml new file mode 100644 index 0000000000..bdf6d3d17d --- /dev/null +++ b/docs/devel/CodingSuggestions.xml @@ -0,0 +1,237 @@ +<chapter id="CodingSuggestions"> +<chapterinfo> + <author> + <firstname>Steve</firstname><surname>French</surname> + </author> + <author> + <firstname>Simo</firstname><surname>Sorce</surname> + </author> + <author> + <firstname>Andrew</firstname><surname>Bartlett</surname> + </author> + <author> + <firstname>Tim</firstname><surname>Potter</surname> + </author> + <author> + <firstname>Martin</firstname><surname>Pool</surname> + </author> +</chapterinfo> + +<title>Coding Suggestions</title> + +<para> +So you want to add code to Samba ... +</para> + +<para> +One of the daunting tasks facing a programmer attempting to write code for +Samba is understanding the various coding conventions used by those most +active in the project. These conventions were mostly unwritten and helped +improve either the portability, stability or consistency of the code. This +document will attempt to document a few of the more important coding +practices used at this time on the Samba project. The coding practices are +expected to change slightly over time, and even to grow as more is learned +about obscure portability considerations. Two existing documents +<filename>samba/source/internals.doc</filename> and +<filename>samba/source/architecture.doc</filename> provide +additional information. +</para> + +<para> +The loosely related question of coding style is very personal and this +document does not attempt to address that subject, except to say that I +have observed that eight character tabs seem to be preferred in Samba +source. If you are interested in the topic of coding style, two oft-quoted +documents are: +</para> + +<para> +<ulink url="http://lxr.linux.no/source/Documentation/CodingStyle">http://lxr.linux.no/source/Documentation/CodingStyle</ulink> +</para> + +<para> +<ulink url="http://www.fsf.org/prep/standards_toc.html">http://www.fsf.org/prep/standards_toc.html</ulink> +</para> + +<para> +But note that coding style in Samba varies due to the many different +programmers who have contributed. +</para> + +<para> +Following are some considerations you should use when adding new code to +Samba. First and foremost remember that: +</para> + +<para> +Portability is a primary consideration in adding function, as is network +compatability with de facto, existing, real world CIFS/SMB implementations. +There are lots of platforms that Samba builds on so use caution when adding +a call to a library function that is not invoked in existing Samba code. +Also note that there are many quite different SMB/CIFS clients that Samba +tries to support, not all of which follow the SNIA CIFS Technical Reference +(or the earlier Microsoft reference documents or the X/Open book on the SMB +Standard) perfectly. +</para> + +<para> +Here are some other suggestions: +</para> + +<orderedlist> + +<listitem><para> + use d_printf instead of printf for display text + reason: enable auto-substitution of translated language text +</para></listitem> + +<listitem><para> + use SAFE_FREE instead of free + reason: reduce traps due to null pointers +</para></listitem> + +<listitem><para> + don't use bzero use memset, or ZERO_STRUCT and ZERO_STRUCTP macros + reason: not POSIX +</para></listitem> + +<listitem><para> + don't use strcpy and strlen (use safe_* equivalents) + reason: to avoid traps due to buffer overruns +</para></listitem> + +<listitem><para> + don't use getopt_long, use popt functions instead + reason: portability +</para></listitem> + +<listitem><para> + explicitly add const qualifiers on parm passing in functions where parm + is input only (somewhat controversial but const can be #defined away) +</para></listitem> + +<listitem><para> + when passing a va_list as an arg, or assigning one to another + please use the VA_COPY() macro + reason: on some platforms, va_list is a struct that must be + initialized in each function...can SEGV if you don't. +</para></listitem> + +<listitem><para> + discourage use of threads + reason: portability (also see architecture.doc) +</para></listitem> + +<listitem><para> + don't explicitly include new header files in C files - new h files + should be included by adding them once to includes.h + reason: consistency +</para></listitem> + +<listitem><para> + don't explicitly extern functions (they are autogenerated by + "make proto" into proto.h) + reason: consistency +</para></listitem> + +<listitem><para> + use endian safe macros when unpacking SMBs (see byteorder.h and + internals.doc) + reason: not everyone uses Intel +</para></listitem> + +<listitem><para> + Note Unicode implications of charset handling (see internals.doc). See + pull_* and push_* and convert_string functions. + reason: Internationalization +</para></listitem> + +<listitem><para> + Don't assume English only + reason: See above +</para></listitem> + +<listitem><para> + Try to avoid using in/out parameters (functions that return data which + overwrites input parameters) + reason: Can cause stability problems +</para></listitem> + +<listitem><para> + Ensure copyright notices are correct, don't append Tridge's name to code + that he didn't write. If you did not write the code, make sure that it + can coexist with the rest of the Samba GPLed code. +</para></listitem> + +<listitem><para> + Consider usage of DATA_BLOBs for length specified byte-data. + reason: stability +</para></listitem> + +<listitem><para> + Take advantage of tdbs for database like function + reason: consistency +</para></listitem> + +<listitem><para> + Don't access the SAM_ACCOUNT structure directly, they should be accessed + via pdb_get...() and pdb_set...() functions. + reason: stability, consistency +</para></listitem> + +<listitem><para> + Don't check a password directly against the passdb, always use the + check_password() interface. + reason: long term pluggability +</para></listitem> + +<listitem><para> + Try to use asprintf rather than pstrings and fstrings where possible +</para></listitem> + +<listitem><para> + Use normal C comments / * instead of C++ comments // like + this. Although the C++ comment format is part of the C99 + standard, some older vendor C compilers do not accept it. +</para></listitem> + +<listitem><para> + Try to write documentation for API functions and structures + explaining the point of the code, the way it should be used, and + any special conditions or results. Mark these with a double-star + comment start / ** so that they can be picked up by Doxygen, as in + this file. +</para></listitem> + +<listitem><para> + Keep the scope narrow. This means making functions/variables + static whenever possible. We don't want our namespace + polluted. Each module should have a minimal number of externally + visible functions or variables. +</para></listitem> + +<listitem><para> + Use function pointers to keep knowledge about particular pieces of + code isolated in one place. We don't want a particular piece of + functionality to be spread out across lots of places - that makes + for fragile, hand to maintain code. Instead, design an interface + and use tables containing function pointers to implement specific + functionality. This is particularly important for command + interpreters. +</para></listitem> + +<listitem><para> + Think carefully about what it will be like for someone else to add + to and maintain your code. If it would be hard for someone else to + maintain then do it another way. +</para></listitem> + +</orderedlist> + +<para> +The suggestions above are simply that, suggestions, but the information may +help in reducing the routine rework done on new code. The preceeding list +is expected to change routinely as new support routines and macros are +added. +</para> +</chapter> |