← Back to branch summary

~zulcss/samba/server-dailies-3.4

« back to all changes in this revision

Viewing changes to docs-xml/Samba3-Developers-Guide/CodingSuggestions.xml

  • Committer: Chuck Short
  • Date: 2010-09-28 20:38:39 UTC
  • Revision ID: zulcss@ubuntu.com-20100928203839-pgjulytsi9ue63x1
Initial version

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs-xml/Samba3-Developers-Guide/CodingSuggestions.xml
 
1
<?xml version="1.0" encoding="iso-8859-1"?>
 
2
<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
 
3
<chapter id="CodingSuggestions">
 
4
<chapterinfo>
 
5
        <author>
 
6
                <firstname>Steve</firstname><surname>French</surname>
 
7
        </author>
 
8
        <author>
 
9
                <firstname>Simo</firstname><surname>Sorce</surname>
 
10
        </author>
 
11
        <author>
 
12
                <firstname>Andrew</firstname><surname>Bartlett</surname>
 
13
        </author>
 
14
        <author>
 
15
                <firstname>Tim</firstname><surname>Potter</surname>
 
16
        </author>
 
17
        <author>
 
18
                <firstname>Martin</firstname><surname>Pool</surname>
 
19
        </author>
 
20
</chapterinfo>
 
21
 
 
22
<title>Coding Suggestions</title>
 
23
 
 
24
<para>
 
25
So you want to add code to Samba ...
 
26
</para>
 
27
 
 
28
<para>
 
29
One of the daunting tasks facing a programmer attempting to write code for
 
30
Samba is understanding the various coding conventions used by those most
 
31
active in the project.  These conventions were mostly unwritten and helped
 
32
improve either the portability, stability or consistency of the code. This
 
33
document will attempt to document a few of the more important coding
 
34
practices used at this time on the Samba project.  The coding practices are
 
35
expected to change slightly over time, and even to grow as more is learned
 
36
about obscure portability considerations.  Two existing documents
 
37
<filename>samba/source/internals.doc</filename> and 
 
38
<filename>samba/source/architecture.doc</filename> provide
 
39
additional information.
 
40
</para>
 
41
 
 
42
<para>
 
43
The loosely related question of coding style is very personal and this
 
44
document does not attempt to address that subject, except to say that I
 
45
have observed that eight character tabs seem to be preferred in Samba
 
46
source.  If you are interested in the topic of coding style, two oft-quoted
 
47
documents are:
 
48
</para>
 
49
 
 
50
<para>
 
51
<ulink url="http://lxr.linux.no/source/Documentation/CodingStyle">http://lxr.linux.no/source/Documentation/CodingStyle</ulink>
 
52
</para>
 
53
 
 
54
<para>
 
55
<ulink url="http://www.fsf.org/prep/standards_toc.html">http://www.fsf.org/prep/standards_toc.html</ulink>
 
56
</para>
 
57
 
 
58
<para>
 
59
But note that coding style in Samba varies due to the many different
 
60
programmers who have contributed.
 
61
</para>
 
62
 
 
63
<para>
 
64
Following are some considerations you should use when adding new code to
 
65
Samba.  First and foremost remember that:
 
66
</para>
 
67
 
 
68
<para>
 
69
Portability is a primary consideration in adding function, as is network
 
70
compatability with de facto, existing, real world CIFS/SMB implementations.
 
71
There are lots of platforms that Samba builds on so use caution when adding
 
72
a call to a library function that is not invoked in existing Samba code.
 
73
Also note that there are many quite different SMB/CIFS clients that Samba
 
74
tries to support, not all of which follow the SNIA CIFS Technical Reference
 
75
(or the earlier Microsoft reference documents or the X/Open book on the SMB
 
76
Standard) perfectly.
 
77
</para>
 
78
 
 
79
<para>
 
80
Here are some other suggestions:
 
81
</para>
 
82
 
 
83
<orderedlist>
 
84
 
 
85
<listitem><para>
 
86
        use d_printf instead of printf for display text
 
87
        reason: enable auto-substitution of translated language text 
 
88
</para></listitem>
 
89
 
 
90
<listitem><para>
 
91
        use SAFE_FREE instead of free
 
92
        reason: reduce traps due to null pointers
 
93
</para></listitem>
 
94
 
 
95
<listitem><para>
 
96
        don't use bzero use memset, or ZERO_STRUCT and ZERO_STRUCTP macros
 
97
        reason: not POSIX
 
98
</para></listitem>
 
99
 
 
100
<listitem><para>
 
101
        don't use strcpy and strlen (use safe_* equivalents)
 
102
        reason: to avoid traps due to buffer overruns
 
103
</para></listitem>
 
104
 
 
105
<listitem><para>
 
106
        don't use getopt_long, use popt functions instead
 
107
        reason: portability
 
108
</para></listitem>
 
109
 
 
110
<listitem><para>
 
111
        explicitly add const qualifiers on parm passing in functions where parm
 
112
        is input only (somewhat controversial but const can be #defined away)
 
113
</para></listitem>
 
114
 
 
115
<listitem><para>
 
116
        when passing a va_list as an arg, or assigning one to another
 
117
        please use the VA_COPY() macro
 
118
        reason: on some platforms, va_list is a struct that must be 
 
119
        initialized in each function...can SEGV if you don't.
 
120
</para></listitem>
 
121
 
 
122
<listitem><para>
 
123
        discourage use of threads
 
124
        reason: portability (also see architecture.doc)
 
125
</para></listitem>
 
126
 
 
127
<listitem><para>
 
128
        don't explicitly include new header files in C files - new h files 
 
129
        should be included by adding them once to includes.h
 
130
        reason: consistency
 
131
</para></listitem>
 
132
 
 
133
<listitem><para>
 
134
        don't explicitly extern functions (they are autogenerated by 
 
135
        "make proto" into proto.h)
 
136
        reason: consistency
 
137
</para></listitem>
 
138
 
 
139
<listitem><para>
 
140
        use endian safe macros when unpacking SMBs (see byteorder.h and
 
141
        internals.doc)
 
142
        reason: not everyone uses Intel
 
143
</para></listitem>
 
144
 
 
145
<listitem><para>
 
146
        Note Unicode implications of charset handling (see internals.doc).  See
 
147
        pull_*  and push_* and convert_string functions.
 
148
        reason: Internationalization
 
149
</para></listitem>
 
150
 
 
151
<listitem><para>
 
152
        Don't assume English only
 
153
        reason: See above
 
154
</para></listitem>
 
155
 
 
156
<listitem><para>
 
157
        Try to avoid using in/out parameters (functions that return data which
 
158
        overwrites input parameters)
 
159
        reason: Can cause stability problems
 
160
</para></listitem>
 
161
 
 
162
<listitem><para>
 
163
        Ensure copyright notices are correct, don't append Tridge's name to code
 
164
        that he didn't write.  If you did not write the code, make sure that it
 
165
        can coexist with the rest of the Samba GPLed code.
 
166
</para></listitem>
 
167
 
 
168
<listitem><para>
 
169
        Consider usage of DATA_BLOBs for length specified byte-data.
 
170
        reason: stability
 
171
</para></listitem>
 
172
 
 
173
<listitem><para>
 
174
        Take advantage of tdbs for database like function
 
175
        reason: consistency
 
176
</para></listitem>
 
177
 
 
178
<listitem><para>
 
179
        Don't access the SAM_ACCOUNT structure directly, they should be accessed
 
180
        via pdb_get...() and pdb_set...() functions.
 
181
        reason: stability, consistency
 
182
</para></listitem>
 
183
 
 
184
<listitem><para>
 
185
        Don't check a password directly against the passdb, always use the
 
186
        check_password() interface.
 
187
        reason: long term pluggability
 
188
</para></listitem>
 
189
 
 
190
<listitem><para>
 
191
        Try to use asprintf rather than pstrings and fstrings where possible
 
192
</para></listitem>
 
193
 
 
194
<listitem><para>
 
195
        Use normal C comments / * instead of C++ comments // like
 
196
        this.  Although the C++ comment format is part of the C99
 
197
        standard, some older vendor C compilers do not accept it.
 
198
</para></listitem>
 
199
 
 
200
<listitem><para>
 
201
        Try to write documentation for API functions and structures
 
202
        explaining the point of the code, the way it should be used, and
 
203
        any special conditions or results.  Mark these with a double-star
 
204
        comment start / ** so that they can be picked up by Doxygen, as in
 
205
        this file.
 
206
</para></listitem>
 
207
 
 
208
<listitem><para>
 
209
        Keep the scope narrow. This means making functions/variables
 
210
        static whenever possible. We don't want our namespace
 
211
        polluted. Each module should have a minimal number of externally
 
212
        visible functions or variables.
 
213
</para></listitem>
 
214
 
 
215
<listitem><para>
 
216
        Use function pointers to keep knowledge about particular pieces of
 
217
        code isolated in one place. We don't want a particular piece of
 
218
        functionality to be spread out across lots of places - that makes
 
219
        for fragile, hand to maintain code. Instead, design an interface
 
220
        and use tables containing function pointers to implement specific
 
221
        functionality. This is particularly important for command
 
222
        interpreters. 
 
223
</para></listitem>
 
224
 
 
225
<listitem><para>
 
226
        Think carefully about what it will be like for someone else to add
 
227
        to and maintain your code. If it would be hard for someone else to
 
228
        maintain then do it another way. 
 
229
</para></listitem>
 
230
 
 
231
</orderedlist>
 
232
 
 
233
<para>
 
234
The suggestions above are simply that, suggestions, but the information may
 
235
help in reducing the routine rework done on new code.  The preceeding list
 
236
is expected to change routinely as new support routines and macros are
 
237
added.
 
238
</para>
 
239
</chapter>