108 marek 1.1 </table>
109 <p> </p>
110 <hr>
111 <p><b>Abstract:</b> This document formalizes the Pegasus coding conventions.
112 </p>
113 <hr>
114
115 <h2><font color="#000000">Definition of the Problem</font></h2>
116 <p><The use of inconsistent coding styles is an impediment to
117 effective development and maintenance of Pegasus code. Formalization of
118 Pegasus coding conventions may help to improve code consistency.
119 </p>
120
121 <h2><font color="#000000">Proposed Solution</font></h2>
122 <p>The following items comprise the Pegasus coding conventions.</p>
123
124 <h3>Formatting</h3>
125 <ol>
126 <li>Indent by increments of four spaces. Indent comments
127 equally with the associated code.</li>
128 <li>Do not use tab characters.</li>
129 marek 1.1 <li>Lines must not span more than 80 columns.</li>
130 <li>Remove trailing spaces at the end of a line.
131 (Note: This also applies to Makefiles, where trailing spaces may cause
132 unintended whitespace in generated files.)</li>
133 <li>Put opening brace on a line by itself, aligned with control keyword
134 or method signature.
135 Do this:
136 <pre><code> for (...)
137 {
138 }</code></pre>
139 Not this:
140 <pre><code> for (...) {
141 }</code></pre>
142 Or this:
143 <pre><code> for (...)
144 {
145 }</code></pre>
146 </li>
147 <li>Use braces around the body of a control block (e.g., <code>if</code>,
148 <code>for</code>, or <code>while</code> statement), even if the body
149 contains just a single statement.
150 marek 1.1 Do this:
151 <pre><code> for (...)
152 {
153 i++;
154 }</code></pre>
155 Not this:
156 <pre><code> for (...)
157 i++;</code></pre>
158 </li>
159 <li>Use a new line for <code>else</code> statements rather
160 than placing then on the same line as a preceding '<code>}</code>'.
161 Do this:
162 <pre><code> if (...)
163 {
164 i++;
165 }
166 else
167 {
168 j++;
169 }</code></pre>
170 Not this:
171 marek 1.1 <pre><code> if (...)
172 {
173 i++;
174 } else
175 {
176 j++;
177 }</code></pre>
178 </li>
179 <li>Use normal indenting for parameters in a complex method signature:
180 <pre><code> void MyClass::myMethod(
181 const char* someReallyLongName,
182 const char* someOtherReallyLongName);</code></pre>
183 </li>
184 <li>Use normal indenting for all arguments in a complex function call.
185 Do this:
186 <pre><code> callingMyFunction(
187 arg1,
188 arg2,
189 arg3);</code></pre>
190 Not this:
191 <pre><code> callingMyFunction(arg1,
192 marek 1.1 arg2,
193 arg3);</code></pre>
194 Each argument should be placed on a separate line.
195 An exception is made for <code>PEG_TRACE</code> and
196 <code>PEG_TRACE_CSTRING</code> statements, where the first two
197 arguments should be placed on the opening line:
198 <pre><code> PEG_TRACE((TRC_HTTP, Tracer::LEVEL3,
199 "Connection IP address = %s",
200 (const char*)_ipAddress.getCString()));</code></pre>
201 </li>
202 <li>For an <code>if</code>, <code>while</code>, or <code>for</code>
203 condition that does not fit on a single line, indent peer subconditions
204 according to their level of nesting and indent other continuation lines
205 using normal indenting. Do this:
206 <pre><code> if ((variable1 == variable2) ||
207 ((anotherVariableToConsider ==
208 variable1 + variable2) &&
209 (dayOfWeek == "Tuesday")))</code></pre>
210 Not this:
211 <pre><code> if ((variable1 == variable2) ||
212 ((anotherVariableToConsider ==
213 marek 1.1 variable1 + variable2) &&
214 (dayOfWeek == "Tuesday")))</code></pre>
215 </li>
216 <li>For a statement that does not fit on a single line,
217 all continuation lines should be indented once from the first line.
218 For example:
219 <pre><code> sum = a + b + c +
220 d + e + f +
221 g + h;</code></pre>
222 </li>
223 <li>Do not separate a return type onto its own line. Avoid this:
224 <pre><code> int
225 f()
226 {
227 }</code></pre>
228 </li>
229 <li>Avoid use of "<code>(void)</code>" for an empty parameter list.
230 Use "<code>()</code>" instead.
231 </li>
232 <li>Avoid adding a space between function/method name the opening parenthesis.
233 Do this:
234 marek 1.1 <pre><code> void f(int i);
235 f(10);</code></pre>
236 Not this:
237 <pre><code> void f (int i);
238 f (10);</code></pre>
239 </li>
240 <li>Include a space between a keyword and an opening parenthesis.
241 Do this:
242 <pre><code> if (i > 0)
243 for (i = 0; i < 10; i++)</code></pre>
244 Not this:
245 <pre><code> if(i > 0)
246 for(i = 0; i < 10; i++)</code></pre>
247 </li>
248 <li>Do not add spaces around a condition. Do this:
249 <pre><code> if (cond)
250 while (cond)</code></pre>
251 Not this:
252 <pre><code> if ( cond )
253 while ( cond )</code></pre>
254 </li>
255 marek 1.1 <li>Do not add a space between a template name and its type. Do this:
256 <pre><code> Array<Uint8> myArray;</code></pre>
257 Not this:
258 <pre><code> Array <Uint8> myArray;</code></pre>
259 </li>
260 <li>Avoid aligning variable names in a declaration list. Do this:
261 <pre><code> int x;
262 float y;</code></pre>
263 Not this:
264 <pre><code> int x;
265 float y;</code></pre>
266 </li>
267 <li>Avoid indenting "<code>public:</code>",
268 "<code>protected:</code>", and
269 "<code>private:</code>". Do this:
270 <pre><code> class X
271 {
272 public:
273 int f();
274 ...
275 private:
276 marek 1.1 int _g();
277 ...
278 };</code></pre>
279 </li>
280 <li>The '<code>#</code>' indicating a preprocessing directive is placed
281 at the beginning of a line. Nested preprocessing directives are
282 indented with one space after the '<code>#</code>' for each level of
283 nesting. The <code>#ifndef</code> used for header file include protection
284 is not considered a level of nesting. For example:
285 <pre><code>#ifdef PEGASUS_HAS_SIGNALS
286 # ifdef PEGASUS_OS_TYPE_WINDOWS
287 # include <windows.h>
288 # else
289 # include <unistd.h>
290 # endif
291 #endif</code></pre>
292 </li>
293 <li>In a <code>switch</code> statement, indent the <code>case</code>
294 statement from the <code>switch</code> and indent the case logic from
295 the <code>case</code> statement. For example:
296 <pre><code> switch(n)
297 marek 1.1 {
298 case 0:
299 printf("Rock");
300 break;
301 case 1:
302 printf("Paper");
303 break;
304 case 2:
305 printf("Scissors");
306 break;
307 default:
308 printf("Error");
309 break;
310 }</code></pre>
311 </li>
312 <li>Do not put parentheses around the return value in a
313 <code>return</code> statement.
314 </li>
315 </ol>
316
317 <h3>Naming</h3>
318 marek 1.1 <ol>
319 <li>For class/struct names, use mixed case with initial upper case and
320 no underscores: <code>ThisIsAClassName</code>.
321 </li>
322 <li>For public member/variable names, use mixed case with initial lower case
323 and no underscores: <code>thisIsAMemberName</code>.
324 </li>
325 <li>For public method/function names, use mixed case with initial lower case
326 and no underscores: <code>thisIsAMethodName()</code>.
327 </li>
328 <li>Prepend an underscore to private and protected member and method names:
329 <code>_thisIsAPrivateMemberName</code>,
330 <code>_thisIsAPrivateMethodName()</code>.
331 </li>
332 <li>General constants and macro names should begin with <code>PEGASUS_</code>.
333 </li>
334 <li>Use this format for constant and macro names:
335 <code>PEGASUS_CONSTANT_NAME</code>.
336 </li>
337 <li>Files names should use mixed case with initial upper case and no
338 underscores: <code>ThisIsAFileName.cpp</code>.
339 marek 1.1 </li>
340 <li>A file should have the same name (and case) as the class it contains.
341 </li>
342 <li>Environment variables must begin with <code>PEGASUS_</code> and have
343 this form: <code>PEGASUS_ENVIRONMENT_VARIABLE</code>.
344 This applies to environment variables that control the build and test
345 configuration as well as those (if any) used by Pegasus at run time.
346 </li>
347 <li>Test executable names should begin with 'Test' (to distinguish them
348 from other executables) and should use mixed case with initial upper
349 case and no underscores. The name should clearly indicate the feature
350 being tested. For example: <code>TestFeature1</code>.
351 </li>
352 </ol>
353
354 <h3>Style</h3>
355 <ol>
356 <li>In a header file, use angle brackets (with a fully qualified path)
357 rather than quotes when including a file. Do this:
358 <pre><code> #include <Pegasus/Common/Array.h></code></pre>
359 Not this:
360 marek 1.1 <pre><code> #include "Array.h"</code></pre>
361 </li>
362 <li>Use "<code>0</code>" rather than "<code>NULL</code>"
363 as a null pointer value.
364 </li>
365 <li>Avoid <code>throw()</code> declarations. These may be used
366 only when a method must not (and will not) throw any exception not
367 specified in the throw clause. When a <code>throw()</code>
368 clause is needed, include it on the method declaration and definition.
369 </li>
370 <li>Use <code>const</code> declarations liberally,
371 but not on "plain old data type" parameters.</li>
372 <li>Catch exceptions by const reference when feasible.</li>
373 <li>Avoid inlining of large functions.</li>
374 <li>Avoid committing binary files to CVS.</li>
375 <li>Resolve compile warnings.</li>
376 <li>Define variables as late as possible.
377 A single object initialization is more efficient than initialization
378 followed by assignment. For example, this logic involves just a single
379 String construction:
380 <pre><code> String s = foo();</code></pre>
381 marek 1.1 while this logic causes two String constructions and an assignment:
382 <pre><code> String s;
383 ...
384 s = foo();</code></pre>
385 </li>
386 <li>Present resources as part of classes, do not use them directly.</li>
387 <li>Use <code>new</code> and <code>delete</code> to manage dynamic
388 memory, not <code>malloc</code>, <code>free</code>, or
389 <code>strdup</code>.</li>
390 <li>When rethrowing an exception from a <code>catch</code>
391 block, avoid specifying the object to throw so that exception subtype
392 information is not lost and construction of an extra exception
393 object is avoided. Do this:
394 <pre><code> catch (Exception&)
395 {
396 ...
397 throw;
398 }</code></pre>
399 Not this:
400 <pre><code> catch (Exception& e)
401 {
402 marek 1.1 ...
403 throw e;
404 }</code></pre></li>
405 <li>Do not check whether a pointer is non-null before
406 deleting it. The check is unnecessary, since it is also performed by
407 the <code>delete</code> operator. Do this:
408 <pre><code> delete ptr;</code></pre>
409 Not this:
410 <pre><code> if (ptr)
411 {
412 delete ptr;
413 }</code></pre></li>
414 <li>Avoid using the compiler default implementations for
415 default constructors, copy constructors, and assignment operators.
416 These should be declared as private and left unimplemented if they
417 are not intended to be used. A decision to use a compiler default
418 should be documented with a comment in the class declaration.</li>
419 <li>Avoid the use of optional parameters in methods which
420 have interface compatibility requirements.</li>
421 <li>Avoid reading variables from the environment in
422 production (not debug or test) runtime code.</li>
423 marek 1.1 <li>Definitions for the external interface declarations should not appear
424 in the external interface header files. Implementation logic for the
425 external interfaces should be contained in the associated source files.
426 </li>
427 <li>Pass object parameters by reference, when feasible,
428 to avoid unnecessary copy constructions. For example, this:
429 <pre><code> void func(const String& s);</code></pre>
430 is preferred to this:
431 <pre><code> void func(String s);</code></pre></li>
432 <li>Avoid using the C++ standard template library (STL) and the standard
433 <code>string</code> class. (These tend to produce bloat and may have
434 portability issues.) These files should not be included:
435 <code><string></code>,
436 <code><vector></code>,
437 <code><map></code>,
438 <code><mmap></code>,
439 <code><set></code>,
440 <code><mset></code>,
441 <code><stack></code>,
442 <code><queue></code>,
443 and other STL header files.</li>
444 marek 1.1 <li>Do not call <code>assert()</code> directly. Instead, use
445 <code>PEGASUS_ASSERT()</code> in production code and
446 <code>PEGASUS_TEST_ASSERT()</code> in test programs.</li>
447 <li>Do not explicitly initialize Pegasus Strings to
448 <code>String::EMPTY</code>. This is the default value.</li>
449 <li>Do not add a null terminator to Pegasus Buffer strings.
450 <code>Buffer::getData()</code> ensures the resulting string is
451 null-terminated.</li>
452 </ol>
453
454 <h3>Documentation</h3>
455 <ol>
456 <li>Class members and methods should be documented with DOC++ comments.</li>
457 <li>Use <code>/** */</code> rather than <code>///</code> for DOC++
458 comments.
459 </li>
460 <li>Use this comment style for DOC++ comments:
461 <pre><code> class X
462 {
463 public:
464
465 marek 1.1 /**
466 Creates widgets.
467 @param numWidgets The number of widgets to create.
468 @return true if successful, false otherwise.
469 */
470 Boolean createWidgets(Uint32 numWidgets);
471 };</code></pre>
472 </li>
473 <li>A description should end with a period, even if it is brief:
474 <pre><code> /**
475 Does something useful.
476 */</code></pre>
477 </li>
478 <li>Add a blank line between documented methods:
479 <pre><code> /**
480 Does something quite useful.
481 */
482 void f();
483
484 /**
485 The previous method has a newline after it
486 marek 1.1 to improve its visibility.
487 */
488 void g();</code></pre>
489 </li>
490 </ol>
491
492 <h3>Portability Considerations</h3>
493 <ol>
494 <li>The use of platform specific <code>#ifdef</code>'s should be minimized
495 and discouraged. It is preferred to abstract the mechanics of
496 dissimilar platforms in separate modules (such as DirPOSIX.cpp vs.
497 DirWindows.cpp) or by using abstraction functions or macros such as
498 those that appear below.</li>
499 <li>In header files, identifiers from the standard library (such as
500 <code>ostream</code>, <code>istream</code>, <code>cout</code>, and
501 <code>cerr</code>) must be enclosed in a <code>PEGASUS_STD()</code>
502 macro (which prepends <code>std::</code> to the argument on some
503 platforms).
504 </li>
505 <li>Do not use the <code>PEGASUS_STD()</code> macro in a source file.
506 Instead, specify <code>PEGASUS_USING_STD;</code> at the beginning of
507 marek 1.1 the file.
508 </li>
509 <li>Do not use <code>PEGASUS_USING_STD;</code> or
510 <code>PEGASUS_USING_PEGASUS;</code> in a header file.
511 </li>
512 <li>Avoid use of conditional compilation for obscuring platform
513 differences. Use platform abstractions in the appropriate platform
514 files or in the System*.cpp files in Common.
515 </li>
516 <li>Windows requires symbols to be explicitly imported/exported from
517 dynamic libraries. Linkage.h files are used to define the necessary
518 linkage macros. Each dynamic library that exports symbols should
519 define a <code>PEGASUS_<LIBRARY>_LINKAGE</code> symbol in a
520 Linkage.h file. Each symbol that is exported from the library
521 must be declared with this linkage macro. For example:
522 <pre><code> class PEGASUS_COMMON_LINKAGE String;
523
524 PEGASUS_COMMON_LINKAGE void globalFunction();</code></pre>
525 </li>
526 <li>A <code>main()</code> function must return an int (required by
527 Windows NT).
528 marek 1.1 </li>
529 <li>Do not use <code>ultostr()</code>; use <code>sprintf()</code>
530 instead.
531 </li>
532 <li>Do not declare a throw clause without parentheses:
533 <pre><code> void f() throw TooBad;</code></pre>
534 </li>
535 <li>Do not include a definition of a static member with its declaration:
536 <pre><code> class X
537 {
538 public:
539
540 static const Uint32 COLOR = 225;
541 };</code></pre>
542 Use this instead:
543 <pre><code> class X
544 {
545 public:
546
547 static const Uint32 COLOR;
548 };</code></pre>
549 marek 1.1 And add the definition in the source file:
550 <pre><code> const Uint32 X::COLOR = 225;</code></pre>
551 </li>
552 <li>Use <code>PEGASUS_64BIT_CONVERSION_WIDTH</code> for
553 printf and scanf conversions of 64-bit integers rather than
554 <code>ll</code> or <code>L</code>.
555 Do this:
556 <pre><code> Sint64 i64 = 10;
557 printf("i64 value = %" PEGASUS_64BIT_CONVERSION_WIDTH "d.\n", i64);</code></pre>
558 Instead of this:
559 <pre><code> Sint64 i64 = 10;
560 printf("i64 value = %lld.\n", i64);</code></pre>
561 </li>
562 <li>Do not include class scoping on methods or members in a class definition.
563 Do this:
564 <pre><code> class X
565 {
566 public:
567
568 int myMethod();
569 };</code></pre>
570 marek 1.1 Not this:
571 <pre><code> class X
572 {
573 public:
574
575 int X::myMethod();
576 };</code></pre>
577 </li>
578 <li>Do not use <code>Pegasus::</code> to scope symbols. Not all platforms
579 support C++ namespaces, and this will cause a compilation failure. If
580 a symbol must be explicitly scoped to the Pegasus namespace, use the
581 <code>PEGASUS_NAMESPACE()</code> macro instead.</li>
582 <li>Use consistent declarations of <code>const</code> parameters in method
583 declarations and definitions.</li>
584 </ol>
585
|
586 marek 1.2 <h3>Avoiding Unused parameter, variables, values, functions ...</h3>
587 <p>In general, avoid unused variables, parameters, values and
588 functions. Many compiler come with support to automatically detect
589 these, use them. The OpenPegasus build using gcc will flag unused variables
590 as errors.
591 The Pegasus Architecture team may completely disallow checkin of code that
592 generates unused* warnings to CVS in the future.<br>
593 </p>
594 <ol>
595 <li>Avoid unused parameter warnings. In case the function
596 signature cannot be changed since the function codes an
597 interface, leave the parameter name off in the function
598 definition while keeping the parameter type in place. In the
599 following example of function <i>main()</i> the parameter <i>argv</i>
600 is used later on but parameter <i>argc</i> is not. Do this:<br>
601 <pre><code>int main(int, void** argv)
602 {
603 };</code></pre>
604 Not this:<br>
605 <pre><code>int main(int argc, void** argv)
606 {
607 marek 1.2 };</code></pre>
608 </li>
609 </ol>
610
|
611 marek 1.1
612 <h2><font color="#000000">Discussion</font></h2>
613 <p>Suggestions for additional conventions are listed here for discussion:
614 <ul>
615 <li>Handling of error conditions (cerr vs. logging) and exceptions</li>
616 <li>Testing (perhaps reference another document)</li>
617 <li>Is it appropriate to make a statement about defining
618 localizable messages in the appropriate message bundle?
619 </li>
620 </ul>
621 </p>
622
623
624 <hr>
625 <p><i><font size="2">Copyright (c) 2005 EMC Corporation; Hewlett-Packard
626 Development Company, L.P.; IBM Corp.; The Open Group;
627 VERITAS Software Corporation</font><br>
628 <br>
629 <font size="1">Permission is hereby granted, free of charge, to any person
630 obtaining a copy of this software and associated documentation files
631 (the "Software"), to deal in the Software without restriction,
632 marek 1.1 including without limitation the rights to use, copy, modify, merge, publish,
633 distribute, sublicense, and/or sell copies of the Software, and to permit
634 persons to whom the Software is furnished to do so, subject to the following
635 conditions:</font><br>
636 <font size="2"><br>
637 </font>
638 <font size="1">THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE
639 INCLUDED IN ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS
640 PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
641 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
642 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
643 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
644 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
645 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
646 SOFTWARE.</font></i></p>
647 <hr>
648 <p>Template last modified: <b>March 9th 2004</b> by <b>Martin Kirk<br>
649 </b>Template version: <b>1.8</b></p>
650
651 </body>
652
653 marek 1.1 </html>
|
Return to
CodingGuidelines.htm
CVS log
Up to [Pegasus] / pegasus / doc