diff options
Diffstat (limited to 'docs/docbook/devdoc/CodingSuggestions.xml')
| -rw-r--r-- | docs/docbook/devdoc/CodingSuggestions.xml | 237 |
1 files changed, 0 insertions, 237 deletions
diff --git a/docs/docbook/devdoc/CodingSuggestions.xml b/docs/docbook/devdoc/CodingSuggestions.xml deleted file mode 100644 index bdf6d3d17d..0000000000 --- a/docs/docbook/devdoc/CodingSuggestions.xml +++ /dev/null @@ -1,237 +0,0 @@ -<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> |