From 0675d01a11d0e99519f85e074791832c73615e7a Mon Sep 17 00:00:00 2001 From: Steve French Date: Tue, 13 Nov 2001 19:23:29 +0000 Subject: List of coding suggestions for submitters (This used to be commit 98b9ff2dd89d2a12178b08f86f846b0875c7c150) --- source3/CodingSuggestions | 86 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 source3/CodingSuggestions (limited to 'source3/CodingSuggestions') diff --git a/source3/CodingSuggestions b/source3/CodingSuggestions new file mode 100644 index 0000000000..cefbf01ccd --- /dev/null +++ b/source3/CodingSuggestions @@ -0,0 +1,86 @@ +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 and + 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. + +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) +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 + + +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 and Andrew Bartlett. \ No newline at end of file -- cgit