sin/samba-mirror
1
0
Fork 0
mirror of https://github.com/samba-team/samba.git synced 2025-03-09 08:58:35 +03:00
Code

Reformatted to 75 columns.

Browse Source 
Converted from DOS CRLF format (hmm).

Added suggestion about C vs C++ comments.
This commit is contained in:
Tim Potter -
parent 7b5b5693f4
commit 104899391c
1 changed files with 114 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

200
source/CodingSuggestions
View File

@ -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.
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.