summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTim Potter <tpot@samba.org>2001-11-14 01:34:34 +0000
committerTim Potter <tpot@samba.org>2001-11-14 01:34:34 +0000
commitdc6688ab95148b70ae65bdd0d9caac95f57d6aee (patch)
tree0f3f4f19477eee0430583cd451d439ee7f77580b
parent6bf5caff8b352383a07802601103994427a4422f (diff)
downloadsamba-dc6688ab95148b70ae65bdd0d9caac95f57d6aee.tar.gz
samba-dc6688ab95148b70ae65bdd0d9caac95f57d6aee.tar.bz2
samba-dc6688ab95148b70ae65bdd0d9caac95f57d6aee.zip
Reformatted to 75 columns.
Converted from DOS CRLF format (hmm). Added suggestion about C vs C++ comments. (This used to be commit 104899391cf75017ef8d14416e4558e81723d702)
-rw-r--r--source3/CodingSuggestions200
1 files changed, 114 insertions, 86 deletions
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.