diff options
Diffstat (limited to 'source3/CodingSuggestions')
| -rw-r--r-- | source3/CodingSuggestions | 160 |
1 files changed, 0 insertions, 160 deletions
diff --git a/source3/CodingSuggestions b/source3/CodingSuggestions deleted file mode 100644 index 5e99bc54ca..0000000000 --- a/source3/CodingSuggestions +++ /dev/null @@ -1,160 +0,0 @@ -/** - -@page CodingSuggestions Coding suggestions - -So you want to add code to Samba ... - -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 -samba/source/internals.doc and samba/source/architecture.doc provide -additional information. - -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: - - http://lxr.linux.no/source/Documentation/CodingStyle - http://www.fsf.org/prep/standards_toc.html - -but note that coding style in Samba varies due to the many different -programmers who have contributed. - -The indent utility can be used to format C files in the general -samba coding style. The arguments you should give to indent are: --bad -bap -br -ce -cdw -nbc -brs -bbb -nbc -npsl -ut -i8 - -Following are some considerations you should use when adding new code to -Samba. First and foremost remember that: - -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. - -Here are some other suggestions: - -1) use d_printf instead of printf for display text - reason: enable auto-substitution of translated language text - -2) use SAFE_FREE instead of free - reason: reduce traps due to null pointers - -3) don't use bzero use memset, or ZERO_STRUCT and ZERO_STRUCTP macros - reason: not POSIX - -4) don't use strcpy and strlen (use safe_* equivalents) - reason: to avoid traps due to buffer overruns - -5) don't use getopt_long, use popt functions instead - reason: portability - -6) explicitly add const qualifiers on parm passing in functions where parm - is input only (somewhat controversial but const can be #defined away) - -7) 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. - -8) discourage use of threads - reason: portability (also see architecture.doc) - -9) 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 - -10) don't explicitly extern functions (they are autogenerated by - "make proto" into proto.h) - reason: consistency - -11) use endian safe macros when unpacking SMBs (see byteorder.h and - internals.doc) - reason: not everyone uses Intel - -12) Note Unicode implications of charset handling (see internals.doc). See - pull_* and push_* and convert_string functions. - reason: Internationalization - -13) Don't assume English only - reason: See above - -14) Try to avoid using in/out parameters (functions that return data which - overwrites input parameters) - reason: Can cause stability problems - -15) 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. - -16) Consider usage of DATA_BLOBs for length specified byte-data. - reason: stability - -17) Take advantage of tdbs for database like function - reason: consistency - -18) Don't access the SAM_ACCOUNT structure directly, they should be accessed - via pdb_get...() and pdb_set...() functions. - reason: stability, consistency - -19) Don't check a password directly against the passdb, always use the - check_password() interface. - reason: long term pluggability - -20) Try to use asprintf rather than pstrings and fstrings where possible - -21) 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. - -22) 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. - -23) 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. - -24) 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. - -25) 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. - -26) Always keep the declaration of a function on one line. The autoprototyper - doesn't catch declarations spread over multiple lines. - Use: -static char foo(int bar) - and not: -static char -foo(int bar) - -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. - -Written by Steve French, with contributions from Simo Sorce, Andrew -Bartlett, Tim Potter, Martin Pool and Jelmer Vernooij. - -**/ |