List of coding suggestions for submitters

(This used to be commit 98b9ff2dd89d2a12178b08f86f846b0875c7c150)

diff --git a/source3/CodingSuggestions b/source3/CodingSuggestions
new file mode 100644 (file)
index 0000000..cefbf01
--- /dev/null
+++ b/source3/CodingSuggestions
@@ -0,0 +1,86 @@
+So you want to add code to Samba ...\r
+\r
+One of the daunting tasks facing a programmer attempting to write code for\r
+Samba is understanding the various coding conventions used by those most\r
+active in the project.  These conventions were mostly unwritten and helped\r
+improve either the portability, stability or consistency of the code. This\r
+document will attempt to document a few of the more important coding practices\r
+used at this time on the Samba project.  The coding practices are expected to\r
+change slightly over time, and even to grow as more is learned about obscure\r
+portability considerations.   Two existing documents samba/source/internals.doc\r
+and samba/source/architecture.doc provide additional information.\r
+\r
+The loosely related question of coding style is very personal and this document\r
+does not attempt to address that subject, except to say that I have observed\r
+that eight character tabs seem to be preferred in Samba source.  If you are\r
+interested in the topic of coding style, two oft-quoted documents are:  \r
+   http://lxr.linux.no/source/Documentation/CodingStyle   and\r
+   http://www.fsf.org/prep/standards_toc.html\r
+but note that coding style in Samba varies due to the many different programmers\r
+who have contributed.\r
+\r
+Following are some considerations you should use when adding new code to Samba.\r
+First and foremost remember that: \r
+\r
+Portability is a primary consideration in adding function, as is network \r
+compatability with de facto, existing, real world CIFS/SMB implementations.\r
+There are lots of platforms that Samba builds on so use caution when adding\r
+a call to a library function that is not invoked in existing Samba code.  Also\r
+note that there are many quite different SMB/CIFS clients that Samba tries\r
+to support, not all of which follow the SNIA CIFS Technical Reference (or the\r
+earlier Microsoft reference documents or the X/Open book on the SMB Standard)\r
+perfectly. \r
+\r
+Here are some other suggestions:\r
+1) use d_printf instead of printf for display text\r
+       reason: enable auto-substitution of translated language text \r
+2) use SAFE_FREE instead of free\r
+       reason: reduce traps due to null pointers\r
+3) don't use bzero use memset, or ZERO_STRUCT and ZERO_STRUCTP macros\r
+       reason: not POSIX\r
+4) don't use strcpy and strlen (use safe_* equivalents)\r
+       reason: to avoid traps due to buffer overruns\r
+5) don't use getopt_long, use popt functions instead\r
+       reason: portability\r
+6) explicitly add const qualifiers on parm passing in functions where\r
+parm is input only (somewhat controversial but const can be #defined away)\r
+8) discourage use of threads\r
+        reason: portability (also see architecture.doc)\r
+9) don't explicitly include new header files in C files - new h files \r
+should be included by adding them once to includes.h\r
+       reason: consistency\r
+10) don't explicitly extern functions (they are autogenerated by \r
+"make proto" into proto.h)\r
+       reason: consistency\r
+11) use endian safe macros when unpacking SMBs (see byteorder.h and internals.doc)  \r
+       reason: not everyone uses Intel\r
+12) Note Unicode implications of charset handling (see internals.doc).  See\r
+pull_*  and push_* and convert_string functions.\r
+       reason: Internationalization\r
+13) Don't assume English only\r
+       reason: See above\r
+14) Try to avoid using in/out parameters (functions that return data which\r
+overwrites input parameters)\r
+       reason: Can cause stability problems\r
+15) Ensure copyright notices are correct, don't append Tridge's name to code\r
+that he didn't write.  If you did not write the code, make sure that it can\r
+coexist with the rest of the Samba GPLed code.\r
+16) Consider usage of DATA_BLOBs for length specified byte-data.\r
+       reason: stability\r
+17) Take advantage of tdbs for database like function\r
+       reason: consistency\r
+18) Don't access the SAM_ACCOUNT structure directly, they should be accessed\r
+via pdb_get...() and pdb_set...() functions.\r
+       reason: stability, consistency\r
+19) Don't check a password directly against the passdb, always use the\r
+check_password() interface.\r
+       reason: long term pluggability\r
+20) Try to use asprintf rather than pstrings and fstrings where possible       \r
+       \r
+       \r
+The suggestions above are simply that, suggestions, but the information may\r
+help in reducing the routine rework done on new code.  The preceeding list\r
+is expected to change routinely as new support routines and macros are added.\r
+\r
+\r
+Written by Steve French, with contributions from Simo Sorce and Andrew Bartlett.
\ No newline at end of file