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