List of coding suggestions for submitters

(This used to be commit 98b9ff2dd89d2a12178b08f86f846b0875c7c150)

1 files changed, 86 insertions, 0 deletions

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