source: trunk/samba/docs/htmldocs/Samba3-Developers-Guide/CodingSuggestions.html @ 30

Last change on this file since 30 was 1, checked in by Paul Smedley, 14 years ago

Initial code import

File size: 8.7 KB
Line 
1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 6. Coding Suggestions</title><link rel="stylesheet" href="samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.68.1"><link rel="start" href="index.html" title="SAMBA Developers Guide"><link rel="up" href="pt02.html" title="Part II. Samba Basics"><link rel="prev" href="internals.html" title="Chapter 5. Samba Internals"><link rel="next" href="contributing.html" title="Chapter 7. Contributing code"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 6. Coding Suggestions</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="internals.html">Prev</a> </td><th width="60%" align="center">Part II. Samba Basics</th><td width="20%" align="right"> <a accesskey="n" href="contributing.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="CodingSuggestions"></a>Chapter 6. Coding Suggestions</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Steve</span> <span class="surname">French</span></h3></div></div><div><div class="author"><h3 class="author"><span class="firstname">Simo</span> <span class="surname">Sorce</span></h3></div></div><div><div class="author"><h3 class="author"><span class="firstname">Andrew</span> <span class="surname">Bartlett</span></h3></div></div><div><div class="author"><h3 class="author"><span class="firstname">Tim</span> <span class="surname">Potter</span></h3></div></div><div><div class="author"><h3 class="author"><span class="firstname">Martin</span> <span class="surname">Pool</span></h3></div></div></div></div><p>
2So you want to add code to Samba ...
3</p><p>
4One of the daunting tasks facing a programmer attempting to write code for
5Samba is understanding the various coding conventions used by those most
6active in the project.  These conventions were mostly unwritten and helped
7improve either the portability, stability or consistency of the code. This
8document will attempt to document a few of the more important coding
9practices used at this time on the Samba project.  The coding practices are
10expected to change slightly over time, and even to grow as more is learned
11about obscure portability considerations.  Two existing documents
12<code class="filename">samba/source/internals.doc</code> and
13<code class="filename">samba/source/architecture.doc</code> provide
14additional information.
15</p><p>
16The loosely related question of coding style is very personal and this
17document does not attempt to address that subject, except to say that I
18have observed that eight character tabs seem to be preferred in Samba
19source.  If you are interested in the topic of coding style, two oft-quoted
20documents are:
21</p><p>
22<a href="http://lxr.linux.no/source/Documentation/CodingStyle" target="_top">http://lxr.linux.no/source/Documentation/CodingStyle</a>
23</p><p>
24<a href="http://www.fsf.org/prep/standards_toc.html" target="_top">http://www.fsf.org/prep/standards_toc.html</a>
25</p><p>
26But note that coding style in Samba varies due to the many different
27programmers who have contributed.
28</p><p>
29Following are some considerations you should use when adding new code to
30Samba.  First and foremost remember that:
31</p><p>
32Portability is a primary consideration in adding function, as is network
33compatability with de facto, existing, real world CIFS/SMB implementations.
34There are lots of platforms that Samba builds on so use caution when adding
35a call to a library function that is not invoked in existing Samba code.
36Also note that there are many quite different SMB/CIFS clients that Samba
37tries to support, not all of which follow the SNIA CIFS Technical Reference
38(or the earlier Microsoft reference documents or the X/Open book on the SMB
39Standard) perfectly.
40</p><p>
41Here are some other suggestions:
42</p><div class="orderedlist"><ol type="1"><li><p>
43        use d_printf instead of printf for display text
44        reason: enable auto-substitution of translated language text
45</p></li><li><p>
46        use SAFE_FREE instead of free
47        reason: reduce traps due to null pointers
48</p></li><li><p>
49        don't use bzero use memset, or ZERO_STRUCT and ZERO_STRUCTP macros
50        reason: not POSIX
51</p></li><li><p>
52        don't use strcpy and strlen (use safe_* equivalents)
53        reason: to avoid traps due to buffer overruns
54</p></li><li><p>
55        don't use getopt_long, use popt functions instead
56        reason: portability
57</p></li><li><p>
58        explicitly add const qualifiers on parm passing in functions where parm
59        is input only (somewhat controversial but const can be #defined away)
60</p></li><li><p>
61        when passing a va_list as an arg, or assigning one to another
62        please use the VA_COPY() macro
63        reason: on some platforms, va_list is a struct that must be
64        initialized in each function...can SEGV if you don't.
65</p></li><li><p>
66        discourage use of threads
67        reason: portability (also see architecture.doc)
68</p></li><li><p>
69        don't explicitly include new header files in C files - new h files
70        should be included by adding them once to includes.h
71        reason: consistency
72</p></li><li><p>
73        don't explicitly extern functions (they are autogenerated by
74        "make proto" into proto.h)
75        reason: consistency
76</p></li><li><p>
77        use endian safe macros when unpacking SMBs (see byteorder.h and
78        internals.doc)
79        reason: not everyone uses Intel
80</p></li><li><p>
81        Note Unicode implications of charset handling (see internals.doc).  See
82        pull_*  and push_* and convert_string functions.
83        reason: Internationalization
84</p></li><li><p>
85        Don't assume English only
86        reason: See above
87</p></li><li><p>
88        Try to avoid using in/out parameters (functions that return data which
89        overwrites input parameters)
90        reason: Can cause stability problems
91</p></li><li><p>
92        Ensure copyright notices are correct, don't append Tridge's name to code
93        that he didn't write.  If you did not write the code, make sure that it
94        can coexist with the rest of the Samba GPLed code.
95</p></li><li><p>
96        Consider usage of DATA_BLOBs for length specified byte-data.
97        reason: stability
98</p></li><li><p>
99        Take advantage of tdbs for database like function
100        reason: consistency
101</p></li><li><p>
102        Don't access the SAM_ACCOUNT structure directly, they should be accessed
103        via pdb_get...() and pdb_set...() functions.
104        reason: stability, consistency
105</p></li><li><p>
106        Don't check a password directly against the passdb, always use the
107        check_password() interface.
108        reason: long term pluggability
109</p></li><li><p>
110        Try to use asprintf rather than pstrings and fstrings where possible
111</p></li><li><p>
112        Use normal C comments / * instead of C++ comments // like
113        this.  Although the C++ comment format is part of the C99
114        standard, some older vendor C compilers do not accept it.
115</p></li><li><p>
116        Try to write documentation for API functions and structures
117        explaining the point of the code, the way it should be used, and
118        any special conditions or results.  Mark these with a double-star
119        comment start / ** so that they can be picked up by Doxygen, as in
120        this file.
121</p></li><li><p>
122        Keep the scope narrow. This means making functions/variables
123        static whenever possible. We don't want our namespace
124        polluted. Each module should have a minimal number of externally
125        visible functions or variables.
126</p></li><li><p>
127        Use function pointers to keep knowledge about particular pieces of
128        code isolated in one place. We don't want a particular piece of
129        functionality to be spread out across lots of places - that makes
130        for fragile, hand to maintain code. Instead, design an interface
131        and use tables containing function pointers to implement specific
132        functionality. This is particularly important for command
133        interpreters.
134</p></li><li><p>
135        Think carefully about what it will be like for someone else to add
136        to and maintain your code. If it would be hard for someone else to
137        maintain then do it another way.
138</p></li></ol></div><p>
139The suggestions above are simply that, suggestions, but the information may
140help in reducing the routine rework done on new code.  The preceeding list
141is expected to change routinely as new support routines and macros are
142added.
143</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="internals.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pt02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="contributing.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 5. Samba Internals </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 7. Contributing code</td></tr></table></div></body></html>
Note: See TracBrowser for help on using the repository browser.