Debian Codegraph @

doc/dapl_coding_style.txt

raw
1 #######################################################################
2 # #
3 # DAPL Coding style reference #
4 # #
5 # Steve Sears #
6 # sjs2 at users.sourceforge.net #
7 # #
8 # 12/13/2002 #
9 # #
10 #######################################################################
11
12 ======================================================================
13 Introduction
14 ======================================================================
15
16 The purpose of this document is to establish the coding style adopted by
17 the team implementing the DAPL reference implementation. The rules
18 presented here were arrived at by consensus, they are intended to
19 provide consistency of implementation and make it intuitive to work with
20 the source code.
21
22 ======================================================================
23 Source code conventions
24 ======================================================================
25
26 1. Brackets
27
28 Brackets should follow C99 conventions and declare a block. The
29 following convention is followed:
30
31 if (x)
32 {
33 statement;
34 statement;
35 }
36
37 The following bracket styles are to be avoided:
38
39 K&R style:
40
41 if (x) { /* DON'T DO THIS */
42 statement;
43 }
44
45 GNU style:
46
47 if (x) /* DON'T DO THIS */
48 {
49 statement;
50 }
51
52 Statements are always indented from brackets.
53
54 Brackets are always used for any statement in order to avoid dangling
55 clause bugs. E.g.
56
57 RIGHT:
58 if ( x )
59 {
60 j = 0;
61 }
62
63 WRONG:
64 if ( x )
65 j = 0;
66
67 2. Indents
68
69 Indents are always 4, tabs 8. A tab may serve as a double
70 indent. Many of the reference implementation file have an emacs
71 format statement at the bottom.
72
73 3. Comments
74
75 Comments are always full C style comments, and never C++
76 style. Comments take the form:
77
78 /*
79 * comment
80 */
81
82 4. Variable Declarations
83
84 Variables are always declared on their own line, we do not declare
85 multiple variables on the same line.
86
87 Variables are never initialized in their declaration, they are
88 initialized in the body of the code.
89
90 5. Function Declarations
91
92 The return type of a function is declared on a separate line from the
93 function name.
94
95 Parameters each receive a line and should be clearly labeled as IN
96 or OUT or INOUT. Parameter declarations begin one tab stop from the
97 margin.
98
99 For example:
100
101 DAT_RETURN
102 dapl_function (
103 IN DAT_IA_HANDLE ia_handle,
104 OUT DAT_EP_HANDLE *ep_handle )
105 {
106 ... function body ...
107 }
108
109 5. White space
110
111 Don't be afraid of white space, the goal is to make the code readable
112 and maintainable. We use white space:
113
114 - One space following function names or conditional expressions. It
115 might be better to say one space before any open parenthesis.
116
117 - Suggestion: One space following open parens and one space before
118 closing parens. Not all of the code follows this convention, use
119 your best judgment.
120
121 Example:
122
123 foo ( x1, x2 );
124
125 6. Conditional code
126
127 We generally try to avoid conditional compilation, but there are
128 certain places where it cannot be avoided. Whenever possible, move
129 the conditional code into a macro or otherwise work to put it into an
130 include file that can be used by the platform (e.g. Linux or Windows
131 osd files), or by the underlying provider (e.g. IBM Torrent or
132 Mellanox Tavor).
133
134 Conditionals should be descriptive, and the associated #endif should
135 contain the declaration. E.g.
136
137 #ifdef THIS_IS_AN_EXAMPLE
138
139 /* code */
140
141 #endif /* THIS_IS_AN_EXAMPLE */
142
143 You may change the ending comment if a #else clause is present. E.g.
144
145 #ifdef THIS_IS_AN_EXAMPLE
146 /* code */
147
148 #else
149 /* other code */
150
151 #endif /* !THIS_IS_AN_EXAMPLE */
152
153
154 ======================================================================
155 Naming conventions
156 ======================================================================
157
158 1. Variable Names
159
160 Variable names for DAPL data structures generally follow their type
161 and should be the same in all source files. A few examples:
162
163 Handles
164 DAT_IA_HANDLE ia_handle
165 DAT_EP_HANDLE ep_handle
166
167 Pointers
168
169 DAPL_IA *ia_ptr;
170 DAPL_EP *ep_ptr;
171
172 2. Return Code Names
173
174 There are at least two different subsystems supported in the DAPL
175 reference implementation. In order to bring sanity to the error
176 space, return codes are named and used for their appropriate
177 subsystem. E.g.
178
179 ib_status: InfiniBand status return code
180 dat_status: DAT/DAPL return code
181
182 3. Function Names
183
184 Function names describe the scope to which they apply. There are
185 essentially three names in the reference implementation:
186
187 dapl_* Name of an exported function visible externally.
188 These functions have a 1 to 1 correspondence to
189 their DAT counterparts.
190
191 dapls_* Name of a function that is called from more than one
192 source file, but is limited to a subsystem.
193
194 dapli_* Local function, internal to a file. Should always be
195 of type STATIC.
196
197
198 ======================================================================
199 Util files
200 ======================================================================
201
202 The Reference implementation is organized such that a single, exported
203 function is located in its' own file. If you are trying to find the DAPL
204 function to create and End Point, it will be found in the dapl version
205 of the DAT function in the spec. E.g.
206
207 dapl_ep_create() is found in dapl_ep_create.c
208 dapl_evd_free() is found in dapl_evd_free.c
209
210 It is often the case that the implementation must interact with data
211 structures or call into other subsystems. All utility functions for a
212 subsystem are gathered into the appropriate "util" file.
213
214 For example, dapl_ep_create must allocate a DAPL_EP structure. The
215 routine to allocate and initialize memory is found in the
216 dapl_ep_util.c file and is named dapl_ep_alloc(). Appropriate routines
217 for the util file are
218
219 - Alloc
220 - Free
221 - Assign defaults
222 - linking routines
223 - Check restrictions
224 - Perform operations on a data structure.
225
226 The idea of a util file is an object oriented idea for a non OO
227 language. It encourages a clean implementation.
228
229 For each util.c file, there is also a util.h file. The purpose of the
230 util include file is to define the prototypes for the util file, and to
231 supply any local flags or values necessary to the subsystem.
232
233 ======================================================================
234 Include files, prototypes
235 ======================================================================
236
237 Include files are organized according to subsystem and/or OS
238 platform. The include directory contains files that are global to the
239 entire source set. Prototypes are found in include files that pertain to
240 the data they support.
241
242 Commenting on the DAPL Reference Implementation tree:
243
244 dapl/common
245 dapl/include
246 Contains global dapl data structures, symbols, and
247 prototypes
248 dapl/tavor
249 Contains tavor prototypes and symbols
250 dapl/torrent
251 Contains torrent prototypes and symbols
252 dapl/udapl
253 Contains include files to support udapl specific files
254 dapl/udapl/linux
255 Contains osd files for Linux
256 dapl/udapl/windows
257 Contains osd files for Windows
258
259 For completeness, the dat files described by the DAT Specification are
260 in the tree under the dat/ subdirectory,
261
262 dat/include/dat/
263
264