From dc6688ab95148b70ae65bdd0d9caac95f57d6aee Mon Sep 17 00:00:00 2001 From: Tim Potter Date: Wed, 14 Nov 2001 01:34:34 +0000 Subject: Reformatted to 75 columns. Converted from DOS CRLF format (hmm). Added suggestion about C vs C++ comments. (This used to be commit 104899391cf75017ef8d14416e4558e81723d702) --- source3/CodingSuggestions | 200 ++++++++++++++++++++++++++-------------------- 1 file changed, 114 insertions(+), 86 deletions(-) (limited to 'source3/CodingSuggestions') diff --git a/source3/CodingSuggestions b/source3/CodingSuggestions index cefbf01ccd..aa19c16d85 100644 --- a/source3/CodingSuggestions +++ b/source3/CodingSuggestions @@ -1,86 +1,114 @@ -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 +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. + +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 + +21) Use normal C comments /* like this */ 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. + +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. -- cgit