docs/coding-style.html

   1 <HTML>
   2 <HEAD>
   3 <TITLE>Dali C++ Coding Style</TITLE>
   4 <!--
   5 green code for good examples, same formatting as <pre> tag
   6 red code for bad examples, same formatting as <pre> tag
   7 details hidden by default
   8 -->
   9 <style type="text/css">
  10 code.good { color:green; white-space:pre; }
  11 code.bad { color:red; white-space:pre; }
  12 article.detail { display:block; }
  13 </style>
  14
  15 <script type="text/javascript">
  16 function toggleVisibility( button, obj )
  17 {
  18   // must have button and object
  19   if( !button || !obj )
  20     return;
  21   var e=document.getElementById( obj );
  22   if( !e )
  23     return;
  24
  25   // initially display property seems to be empty, then none
  26   if( e.style.display == "" || e.style.display == "none" )
  27   {
  28     // paragraph shown
  29     button.value="Hide";
  30     e.style.display="block";
  31   }
  32   else
  33   {
  34     // paragraph hidden
  35     button.value="Show";
  36     e.style.display="none";
  37   }
  38 }
  39 </script>
  40
  41 </HEAD>
  42 <BODY>
  43
  44 <H1>Naming</H1>
  45   <P>
  46     The most important consistency rules are those that govern
  47     naming. The style of a name immediately informs us what sort of
  48     thing the named entity is: a type, a variable, a function, a
  49     constant, a macro, etc., without requiring us to search for the
  50     declaration of that entity. The pattern-matching engine in our
  51     brains relies a great deal on these naming rules.
  52   </P>
  53   <P>
  54     Consistency is more important than individual preferences so regardless of
  55     whether you find them sensible or not, the rules are the rules.
  56   </P>
  57
  58   <ARTICLE>
  59     <H2>General Naming Rules</H2>
  60       <SUMMARY>
  61         Function names, variable names, and filenames should be
  62         descriptive; eschew abbreviation.  Types and variables should be
  63         nouns, while functions should be "command" verbs.
  64       </SUMMARY>
  65       <H3>How to Name <input type="button" value="Hide" onclick="toggleVisibility( this, 'how_to_name' );"/></H3>
  66       <ARTICLE class="detail" id="how_to_name">
  67         <P>
  68           Give as descriptive a name as possible, within reason. Do
  69           not worry about saving horizontal space as it is far more
  70           important to make your code immediately understandable by a
  71           new reader. Examples of well-chosen names:
  72         </P>
  73         <CODE class="good">
  74           int numberOfErrors;              // Good.
  75           int countCompletedConnections;   // Good.
  76         </CODE>
  77         <P>
  78           Poorly-chosen names use ambiguous abbreviations or arbitrary
  79           characters that do not convey meaning:
  80         </P>
  81         <CODE class="bad">
  82           int n;                           // Bad - meaningless.
  83           int nerr;                        // Bad - ambiguous abbreviation.
  84           int n_comp_conns;                // Bad - ambiguous abbreviation.
  85         </CODE>
  86         <P>
  87           Type and variable names should typically be nouns: e.g.,
  88           <code>FileOpener</code>,
  89           <code>NumErrors</code>.
  90         </P>
  91         <P>
  92           Function names should typically be imperative (that is they should be commands):
  93                   e.g., <code>OpenFile()</code>, <code>set_num_errors()</code>.  There is an exception for
  94           accessors, which should be named the same as the variable they access.
  95         </P>
  96       </ARTICLE>
  97
  98       <H3>Abbreviations <input type="button" value="Hide" onclick="toggleVisibility( this, 'abbreviations' );"/></H3>
  99       <ARTICLE class="detail" id="abbreviations">
 100         <P>
 101           Do not use abbreviations unless they are extremely well
 102           known outside your project. For example:
 103         </P>
 104         <CODE class="good">
 105           // Good
 106           // These show proper names with no abbreviations.
 107           int numberOfDnsConnections;  // Most people know what "DNS" stands for.
 108           int priceCountReader;   // OK, price count. Makes sense.
 109         </CODE>
 110         <CODE class="bad">
 111           // Bad!
 112           // Abbreviations can be confusing or ambiguous outside a small group.
 113           int wgcconnections;  // Only your group knows what this stands for.
 114           int pcreader;        // Lots of things can be abbreviated "pc".
 115         </CODE>
 116         <P>
 117           Never abbreviate by leaving out letters:
 118         </P>
 119         <CODE class="good">
 120           int error_count;  // Good.
 121         </CODE>
 122         <CODE class="bad">
 123           int error_cnt;    // Bad.
 124         </CODE>
 125       </ARTICLE>
 126   </ARTICLE>
 127
 128   <ARTICLE>
 129     <H2>File Names</H2>
 130     <SUMMARY>
 131       Filenames should be all lowercase and can include underscores dashes (<code>-</code>).
 132       Do not use underscores in filenames (<code>_</code>).
 133     </SUMMARY>
 134     <H3>Examples <input type="button" value="Hide" onclick="toggleVisibility( this, 'file_name_examples' );"/></H3>
 135     <ARTICLE class="detail" id="file_name_examples">
 136       <P>
 137         Examples of acceptable file names:
 138       </P>
 139       <P>
 140         <CODE class="good">
 141           my-useful-class.cpp
 142           myusefulclass.cpp
 143           myusefulclass-test.cpp
 144         </CODE>
 145       </P>
 146       <P>
 147         C++ files should end in <code>.cpp</code> and header files
 148         should end in <code>.h</code>.
 149       </P>
 150       <P>
 151         Do not use filenames that already exist
 152         in <code>/usr/include</code>, such as <code>db.h</code>.
 153       </P>
 154       <P>
 155         In general, make your filenames very specific.  For example,
 156         use <code>http-server-logs.h</code> rather than <code>logs.h</code>.
 157                 A class called <code>FooBar</code> should be declared in file
 158                 called <code>foobar.h</code> and defined in <code>foobar.cpp</code>.
 159       </P>
 160       <P>
 161         Inline functions must be in a <code>.h</code> file. If your
 162         inline functions are very short, they should go directly into your
 163         <code>.h</code> file. However, if your inline functions
 164         include a lot of code, they may go into a third file that
 165         ends in <code>-inl.h</code>.  In a class with a lot of inline
 166         code, your class could have three files:
 167       </P>
 168       <CODE class="good">
 169         foobar.h      // The class declaration.
 170         foobar.cpp     // The class definition.
 171         foobar-inl.h  // Inline functions that include lots of code.
 172       </CODE>
 173     </ARTICLE>
 174   </ARTICLE>
 175
 176   <ARTICLE>
 177     <H2>Type Names</H2>
 178     <SUMMARY>
 179       Type names start with a capital letter and have a capital
 180       letter for each new word, with no underscores:
 181       <code>MyExcitingClass</code>, <code>MyExcitingEnum</code>.
 182       All type names are declared inside namespace so no prefixing is used.
 183     </SUMMARY>
 184     <H3>Examples <input type="button" value="Hide" onclick="toggleVisibility( this, 'type_name_examples' );"/></H3>
 185     <ARTICLE class="detail" id="type_name_examples">
 186       <p>
 187         The names of all types; classes, structs, typedefs have the same naming convention.
 188         Type names start with a capital letter and have a capital letter for each new word (CamelCase).
 189         No underscores. Enumerated types use same convention as Constants> all capitals.
 190         For example:
 191       </p>
 192       <CODE class="good">
 193         // classes and structs
 194         class UrlTable { ...
 195         class UrlTableTester { ...
 196         struct UrlTableProperties { ...
 197
 198         // typedefs
 199         typedef hash_map<UrlTableProperties *, string> PropertiesMap;
 200
 201         // enums
 202         enum UrlTableErrors
 203         {
 204           OK = 0,
 205           OUT_OF_MEMORY = 1,
 206           MALFORMED_INPUT = 2,
 207         }
 208       </CODE>
 209     </ARTICLE>
 210   </ARTICLE>
 211
 212   <ARTICLE>
 213     <H2>Variable Names</H2>
 214     <SUMMARY>
 215       Local variable names start with a lowercase. For example: <code>myExcitingLocalVariable</code>,
 216       Class member variables have prefix m. For example: <code>mMember</code>.
 217       The only exception to this rule is for public member variables in public structs where the prefix m is not required.
 218       Such member variables should also start with a lowercase letter.
 219       Constants should be all capitals.
 220       Avoid underscore characters in names because it can be hard to spot.
 221       Global variables should be avoided, if one is needed, prefix it with <code>g</code>.
 222     </SUMMARY>
 223     <H3>Examples <input type="button" value="Hide" onclick="toggleVisibility( this, 'variable_name_examples' );"/></H3>
 224     <ARTICLE class="detail" id="variable_name_examples">
 225       <p>
 226         For example:
 227       </p>
 228       <CODE class="good">
 229         string tableName;  // OK - starts lowercase
 230         string tablename;   // OK - all lowercase.
 231       </CODE>
 232       <CODE class="bad">
 233         string TableName;   // Bad - starts with capital.
 234       </CODE>
 235       <CODE class="good">
 236         struct Foo
 237         {
 238         string mTable;  // OK
 239         string mTableName;   // OK.
 240         }
 241       </CODE>
 242       <CODE class="good">
 243         const int DAYSINAWEEK = 7;
 244       </CODE>
 245     </ARTICLE>
 246   </ARTICLE>
 247
 248   <ARTICLE>
 249     <H2>Function Names</H2>
 250     <SUMMARY>
 251       Regular functions have camel case starting with uppercase; accessors and mutators match
 252       the name of the variable with Get or Set as prefix. No underscores
 253     </SUMMARY>
 254     <H3>Examples <input type="button" value="Hide" onclick="toggleVisibility( this, 'function_name_examples' );"/></H3>
 255     <ARTICLE class="detail" id="function_name_examples">
 256       <CODE class="good">
 257         MyExcitingFunction();
 258         MyExcitingMethod();
 259
 260         class MyClass
 261         {
 262         public:
 263           ...
 264           int GetNumEntries() const { return mNumEntries; }
 265           void SetNumEntries(int numEntries) { mNumEntries = numEntries; }
 266
 267         private:
 268           int mNumEntries;
 269         };
 270       </CODE>
 271     </ARTICLE>
 272   </ARTICLE>
 273
 274   <ARTICLE>
 275     <H2>Macro Names</H2>
 276     <SUMMARY>
 277       Macros should not be used for programming, code should always be readable without preprocessor.
 278       Only allowed cases for macros are include guards, debug tracing and compile time feature flags
 279       <b>inside</b> .cpp files when no other variation mechanism is not possible. Always prefer variation
 280       through design and template mechanisms rather than <i>#define</i>.
 281       If you need to use macros, they're like this: <code>MY_MACRO_THAT_SCARES_SMALL_CHILDREN</code>.
 282     </SUMMARY>
 283     <H3>Examples <input type="button" value="Hide" onclick="toggleVisibility( this, 'macro_name_examples' );"/></H3>
 284     <ARTICLE class="detail" id="macro_name_examples">
 285       <CODE class="good">
 286         #define DEBUG_TRACE( __FILE__, __LINE__ ) ...
 287         #ifndef __ACTOR_H__
 288         #define __ACTOR_H__
 289         ...
 290         #endif // __ACTOR_H__
 291       </CODE>
 292     </ARTICLE>
 293   </ARTICLE>
 294
 295 <H1>Comments</H1>
 296   <SUMMARY>
 297     Comments are absolutely vital to keeping our code readable.
 298     The following rules describe what you should comment and where.
 299     But remember: while comments are very important, the best code is self-documenting.
 300     Giving sensible names to types and variables is much better than using obscure
 301     names that you must then explain through comments.
 302     When writing your comments, write for your audience: the next
 303     contributor who will need to understand your code.
 304   </SUMMARY>
 305   <H2>Comment Rules <input type="button" value="Hide" onclick="toggleVisibility( this, 'comments_details' );"/></H2>
 306   <ARTICLE class="detail" id="comments_details">
 307     <H3>Comment Style</H3>
 308       <SUMMARY>
 309         API documentation must use doxygen comments:   /** */ or /// <BR>
 310         Internal comments can use <CODE>//</CODE> or <CODE>/* */</CODE> syntax, as long
 311         as you are consistent.
 312       </SUMMARY>
 313     <H3>File Comments</H3>
 314       <SUMMARY>
 315         Start each header file with a guard macro.<BR>
 316         This should match the name of the class which is defined in the file,
 317         including the namespace.<BR>
 318         For example, a class in the Dali namespace called Actor would have the guard:<BR><BR> __DALI_ACTOR_H__<BR><BR>
 319         An Actor class in the Dali::Internal namespace would have the guard:<BR><BR> __DALI_INTERNAL_ACTOR_H__<BR><BR>
 320         The copyright & legal notice should follow the guard macro (inside the #ifdef), since this will improve build times.<BR><BR>
 321         Start each source file with the copyright & legal notice.
 322       </SUMMARY>
 323     <H3>Class Comments</H3>
 324       <SUMMARY>
 325         Every class definition should have an accompanying comment that
 326         describes what it is for and how it should be used.
 327       </SUMMARY>
 328       <CODE class="good">
 329         /**
 330          * Iterates over the contents of a GargantuanTable.
 331          * Example usage:
 332          *    GargantuanTableIterator* iter = table-&gt;NewIterator();
 333          *    for (iter-&gt;Seek("foo"); !iter-&gt;done(); iter-&gt;Next()) {
 334          *      process(iter-&gt;key(), iter-&gt;value());
 335          *    }
 336          *    delete iter;
 337          */
 338         class GargantuanTableIterator
 339         {
 340           ...
 341         };
 342       </CODE>
 343       <P>
 344         Document the synchronization assumptions the class makes, if
 345         any. If an instance of the class can be accessed by multiple
 346         threads, take extra care to document the rules and invariants
 347         surrounding multithreaded use.
 348       </P>
 349     <H3>Function Comments</H3>
 350       <SUMMARY>
 351         Every function declaration (typically in a header file) must have comments immediately
 352         preceding it that describe what the function does and how to use it.  These comments
 353         should be descriptive ("Opens the file") rather than imperative ("Open the file"); the
 354         comment describes the function, it does not tell the function what to do.
 355       </SUMMARY>
 356       <P>
 357         Types of things to mention in comments at the function
 358         declaration:
 359       </P>
 360       <UL>
 361         <LI> What the inputs and outputs are.</LI>
 362         <LI> For class member functions:  whether the object
 363               remembers reference arguments beyond the
 364               duration of the method call, and whether it will
 365               free them or not. </LI>
 366         <LI> If the function allocates memory that the caller
 367               must free. </LI>
 368         <LI> Whether any of the arguments can be <CODE>NULL</CODE> </LI>
 369         <LI> If there are any performance implications of how a function is used.</LI>
 370         <LI> If the function is re-entrant.  What are its synchronization assumptions? </LI>
 371       </UL>
 372         <CODE class="good">
 373           /**
 374            * Get the iterator for this data table. Client's responsibility is to delete the iterator,
 375            * and it must not use the iterator once the GargantuanTable object
 376            * on which the iterator was created has been deleted.
 377            *
 378            * The iterator is initially positioned at the beginning of the table.
 379            *
 380            * This method is equivalent to:
 381            *    Iterator* iter = table->NewIterator();
 382            *    iter->Seek("");
 383            *    return iter;
 384            * If you are going to immediately seek to another place in the
 385            * returned iterator, it will be faster to use NewIterator()
 386            * and avoid the extra seek.
 387            * @return an iterator for this table.
 388            */
 389           Iterator* GetIterator() const;
 390         </CODE>
 391         <P>
 392           When commenting constructors and destructors, remember that
 393           the person reading your code knows what constructors and
 394           destructors are for, so comments that just say something like
 395           "destroys this object" are not useful.
 396         </P>
 397     <H3>Variable Comments</H3>
 398       <SUMMARY>
 399         In general the actual name of the variable should be descriptive
 400         enough to give a good idea of what the variable is used for. In
 401         certain cases, more comments are required.
 402       </SUMMARY>
 403       <CODE class="good">
 404         private:
 405         // Keeps track of the total number of entries in the table.
 406         // Used to ensure we do not go over the limit. -1 means
 407         // that we don't yet know how many entries the table has.
 408         int mNumTotalEntries;
 409       </CODE>
 410     <H3> Duplicate documentation</H3>
 411     <SUMMARY>
 412         Try to avoid duplicate documentation by using the @copydoc command.
 413     </SUMMARY>
 414     <P>
 415        @copydoc copies a documentation block from the object specified by
 416        link-object and pastes it at the location of the command.
 417        This command can be useful to avoid cases where a documentation block
 418        would otherwise have to be duplicated or it can be used to extend the
 419        documentation of an inherited member.
 420     </P>
 421     <CODE class="good">
 422      /*! @copydoc MyClass::myfunction()
 423       *  More documentation.
 424       */
 425     </CODE>
 426      <P>
 427        if the member is overloaded, you should specify the argument types
 428       explicitly (without spaces!), like in the following:
 429      </P>
 430      <CODE class="good">
 431       /*! @copydoc MyClass::myfunction(type1,type2) */
 432      </CODE>
 433     <H3>Punctuation, Spelling and Grammar</H3>
 434       <SUMMARY>
 435         Pay attention to punctuation, spelling, and grammar; it is
 436         easier to read well-written comments than badly written ones.
 437       </SUMMARY>
 438       <P>
 439         Comments should usually be written as complete
 440         sentences with proper capitalization and periods at the end.
 441         Shorter comments, such as comments at the end of a line of
 442         code, can sometimes be less formal, but you should be
 443         consistent with your style.  Complete sentences are more
 444         readable, and they provide some assurance that the comment is
 445         complete and not an unfinished thought.
 446       </P>
 447     <H3>TODO Comments</H3>
 448       <SUMMARY>
 449         Use <code>TODO</code> comments for code that is temporary, a
 450         short-term solution, or good-enough but not perfect.
 451       </SUMMARY>
 452     <H3>Deprecation Comments</H3>
 453       <SUMMARY>
 454         Mark deprecated interface points with <code>DEPRECATED</code> comments.
 455       </SUMMARY>
 456   </ARTICLE>
 457
 458 <H1>Formatting</H1>
 459
 460   <SUMMARY>
 461     A project is much easier to follow if everyone uses the same style.
 462     It is important that all contributors follow the style rules so that
 463     they can all read and understand everyone's code easily.
 464   </SUMMARY>
 465
 466   <H2>Formatting Rules <input type="button" value="Hide" onclick="toggleVisibility( this, 'formatting_rules' );"/></H2>
 467   <ARTICLE class="detail" id="formatting_rules">
 468     <H3>Basic Rules</H3>
 469     <UL>
 470       <LI>Use only spaces, and indent 2 spaces at a time</LI>
 471       <LI>Avoid unnecessary trailing whitescape</LI>
 472       <LI>Avoid overly long lines, modern screens and editors can handle upto 120 characters</LI>
 473       <LI>Use UTF-8 formatting for non-ASCII characters</LI>
 474     </UL>
 475     <P>
 476     Hex encoding is also OK, and encouraged where it enhances
 477     readability &#8212; for example, <code>"\xEF\xBB\xBF"</code> is the
 478     Unicode zero-width no-break space character, which would be
 479     invisible if included in the source as straight UTF-8.
 480     </P>
 481
 482     <H3>Class Format</H3>
 483       <SUMMARY>
 484         Sections in <code>public</code>, <code>protected</code> and
 485         <code>private</code> order.
 486         Typedefs and Enums first, Constructor(s) & Destructors & public API next, then virtual methods and implementation details last.
 487       </SUMMARY>
 488       <CODE class="good">
 489
 490         /**
 491           * Class documentation
 492           */
 493         class MyClass : public Base
 494         {
 495         public: // API
 496
 497           /**
 498            * Documentation
 499            */
 500           MyClass();  // 2 space indent.
 501
 502           /**
 503            * Documentation
 504            */
 505           explicit MyClass( int var );
 506
 507           /**
 508            * Documentation
 509            */
 510           virtual ~MyClass() {}
 511
 512           /**
 513            * Documentation
 514            */
 515           void SomeFunction();
 516
 517           /**
 518            * Documentation
 519            */
 520           void SomeFunctionThatDoesNothing();
 521
 522           /**
 523            * Documentation
 524            */
 525           void SetSomeVar( int var )
 526
 527           /**
 528            * Documentation
 529            */
 530           int GetSomeVar() const
 531
 532         private: // Implementation
 533
 534           MyClass( MyClass& aRHs ); // no copying
 535           MyClass& operator=( const MyClass& aRHs );  // no copying.
 536           bool SomeInternalFunction();
 537
 538           int mSomeVar;
 539           int mSomeOtherVar;
 540         };
 541       </CODE>
 542
 543     <H3>Constructor Initializer Lists</H3>
 544       <SUMMARY>
 545         Constructor initializer lists can be all on one line or with subsequent lines indented.
 546         Always initialize things in declaration order, base class first!!
 547       </SUMMARY>
 548       <CODE class="good">
 549         // When it all fits on one line:
 550         MyClass::MyClass( int var ) : Base( var), mSomeVar( var ), mSomeOtherVar( var + 1 ) {}
 551
 552         // When it requires multiple lines, indent, putting the colon on
 553         // the first initializer line:
 554         MyClass::MyClass( int var )
 555         : Base( var )
 556           mSomeVar( var ),
 557           mSomeOtherVar( var + 1 )
 558         {
 559           DoSomething();
 560         }
 561       </CODE>
 562
 563     <H3>Namespace Formatting</H3>
 564       <SUMMARY>
 565         The contents of namespaces are not indented.
 566       </SUMMARY>
 567       <CODE class="good">
 568         namespace
 569         {
 570         void foo()
 571         {  // Correct.  No extra indentation within namespace.
 572           ...
 573         }
 574         }  // namespace
 575       </CODE>
 576       <P>
 577         When declaring nested namespaces, put each namespace on its own line.
 578       </P>
 579       <CODE class="good">
 580         namespace foo
 581         {
 582         namespace bar
 583         {
 584       </CODE>
 585
 586     <H3>Function Declarations and Definitions</H3>
 587       <SUMMARY>
 588         Return type on the same line as function name, parameters on the same line if they fit.
 589         All parameters should be named, with identical names in the declaration and definition.
 590       </SUMMARY>
 591       <CODE class="good">
 592         ReturnType ClassName::FunctionName( Type par_name1, Type par_name2 )
 593         {
 594           DoSomething();
 595         }
 596       </CODE>
 597       <P>
 598         If you have too much text to fit on one line:
 599       </P>
 600       <CODE class="good">
 601         ReturnType ClassName::ReallyLongFunctionName( Type par_name1, Type par_name2,
 602                                                       Type par_name3 )
 603         {
 604           DoSomething();
 605         }
 606       </CODE>
 607       <P>
 608         or if you cannot fit even the first parameter:
 609       </P>
 610       <CODE class="good">
 611         ReturnType LongClassName::ReallyReallyReallyLongFunctionName(
 612           Type par_name1,  // indent
 613           Type par_name2,
 614           Type par_name3 )
 615         {
 616           DoSomething();  // 2 space indent
 617           ...
 618         }
 619       </CODE>
 620       <P>
 621         <code>const</code> keyword should be on the same line as the last parameter:
 622       </P>
 623       <CODE class="good">
 624         // Everything in this function signature fits on a single line
 625         ReturnType FunctionName( Type par ) const
 626         {
 627           ...
 628         }
 629
 630         // This function signature requires multiple lines, but
 631         // the const keyword is on the line with the last parameter.
 632         ReturnType ReallyLongFunctionName( Type par1,
 633                                            Type par2 ) const
 634         {
 635           ...
 636         }
 637       </CODE>
 638       <P>
 639         If some parameters are unused, comment out the variable name in the function definition:
 640       </P>
 641       <CODE class="good">
 642         // Always have named parameters in interfaces.
 643         class Shape
 644         {
 645         public:
 646           virtual void Rotate( double radians ) = 0;
 647         }
 648
 649         // Always have named parameters in the declaration.
 650         class Circle : public Shape
 651         {
 652         public:
 653           virtual void Rotate( double radians );
 654         }
 655
 656         // Comment out unused named parameters in definitions.
 657         void Circle::Rotate(double /*radians*/) {}
 658       </CODE>
 659       <CODE class="bad">
 660         // Bad - if someone wants to implement later, it's not clear what the
 661         // variable means.
 662         void Circle::Rotate( double ) {}
 663       </CODE>
 664
 665     <H3>Function Calls</H3>
 666       <SUMMARY>
 667         On one line if it fits; otherwise, wrap arguments at the parenthesis. Put one space inside the parentheses, none outside.
 668       </SUMMARY>
 669       <BODY>
 670         <CODE class="good">
 671           bool retval = DoSomething( argument1, argument2, argument3 );
 672         </CODE>
 673         <P>
 674           If the arguments do not all fit on one line, they should be
 675           broken up onto multiple lines, with each subsequent line
 676           aligned with the first argument:
 677         </P>
 678         <CODE class="good">
 679           bool retval = DoSomething( averyveryveryverylongargument1,
 680                                      argument2, argument3 );
 681         </CODE>
 682         <P>
 683           If the function has many arguments, consider having one per
 684           line if this makes the code more readable:
 685         </P>
 686         <CODE class="good">
 687           bool retval = DoSomething( argument1,
 688                                      argument2,
 689                                      argument3,
 690                                      argument4 );
 691         </CODE>
 692         <P>
 693           If the function signature is so long that it cannot fit,
 694           place all arguments on subsequent lines:
 695         </P>
 696         <CODE class="good">
 697           if( ... )
 698           {
 699             DoSomethingThatRequiresALongFunctionName(
 700               very_long_argument1,  // indent
 701               argument2,
 702               argument3,
 703               argument4);
 704           }
 705         </CODE>
 706
 707     <H3>Conditionals</H3>
 708       <SUMMARY>
 709         <code>else</code> keyword belongs on its own line. Put one space inside the parentheses, none outside.
 710       </SUMMARY>
 711       <CODE class="good">
 712         if( condition ) // space inside
 713         {
 714           ...
 715         }
 716         else
 717         {
 718           ...
 719         }
 720       </CODE>
 721       <CODE class="bad">
 722         if(condition)     // Bad - space missing after IF.
 723         if(condition){    // Doubly bad.
 724       </CODE>
 725       <P>
 726         Short conditional statements may be written on one line if
 727         this enhances readability.  You may use this only when the
 728         line is brief and the statement does not use the
 729         <code>else</code> clause.
 730       </P>
 731       <CODE class="good">
 732         if( x == kFoo ) return new Foo();
 733         if( x == kBar ) return new Bar();
 734       </CODE>
 735       <P>
 736         This is not allowed when the if statement has an
 737         <code>else</code>:
 738       </P>
 739       <CODE class="bad">
 740         // Not allowed - IF statement on one line when there is an ELSE clause
 741         if (x) DoThis();
 742         else DoThat();
 743       </CODE>
 744       <P>
 745         In general, prefer curly braces for conditional
 746       </P>
 747       <CODE class="good">
 748         if( condition )
 749         {
 750           DoSomething();  // 2 space indent.
 751         }
 752       </CODE>
 753       <P>
 754         If one part of an <code>if</code>-<code>else</code>
 755         statement uses curly braces, the other part must too:
 756       </P>
 757         <CODE class="bad">
 758           // Not allowed - curly on IF but not ELSE
 759           if (condition) // space outside, not inside
 760           {
 761             foo;
 762           }
 763           else
 764             bar;
 765
 766           // Not allowed - curly on ELSE but not IF
 767           if (condition)
 768             foo;
 769           else
 770           {
 771             bar;
 772           }
 773         </CODE>
 774
 775     <H3>Loops and Switch Statements</H3>
 776       <SUMMARY>
 777         Switch statements use braces for blocks. Empty loop bodies must use
 778         <code>{}</code> or <code>continue</code>.
 779         Switch statements should always have a <code>default</code> case
 780         unless they switch on an <code>enum</code> type,
 781         for which the compiler will ensure all values are handled.
 782
 783         If the default case should never execute, simply <code>assert</code>.
 784         Put one space inside the parentheses, none outside.
 785       </SUMMARY>
 786       <P>
 787         <code>case</code> blocks in <code>switch</code> statements must have
 788         curly braces.
 789         They should be placed as shown below.
 790       </P>
 791
 792       <CODE class="good">
 793         switch( var )
 794         {
 795           case 0: // 2 space indent
 796           {
 797             ...      // 2 space indent
 798             break;
 799           }
 800           case 1:
 801           {
 802             ...
 803             break;
 804           }
 805           default:
 806           {
 807             DALI_ASSERT_ALWAYS( false );
 808           }
 809         }
 810       </CODE>
 811       <P>
 812         Empty loop bodies should use <code>{}</code> or
 813         <code>continue</code>, but not a single semicolon.
 814       </P>
 815       <CODE class="good">
 816         while( condition )
 817         {
 818           // Repeat test until it returns false.
 819         }
 820         for( int i = 0; i < someNumber; ++i )
 821           {}  // Good - empty body, clearly on its own line
 822         while( condition )
 823           continue;  // Good - continue indicates no logic.
 824       </CODE>
 825       <CODE class="bad">
 826         while (condition);  // Bad - looks like part of do/while loop.
 827       </CODE>
 828     <H3>Pointer and Reference Expressions</H3>
 829       <SUMMARY>
 830         No spaces around period or arrow.  Pointer operators do not have trailing spaces.
 831       </SUMMARY>
 832       <P>
 833         The following are examples of correctly-formatted pointer and
 834         reference expressions:
 835       </P>
 836       <CODE class="good">
 837         x = *p;
 838         p = &amp;x;
 839         x = r.y;
 840         x = r-&gt;y;
 841       </CODE>
 842       <P>
 843         When declaring a pointer variable or argument, you may place
 844         the asterisk adjacent to either the type or to the variable
 845         name:
 846       </P>
 847       <CODE class="good">
 848         // These are fine, space preceding.
 849         char *c;
 850         const string &amp;str;
 851
 852         // These are fine, space following.
 853         char* c;    // but remember to do each variable on its own line or "char* c, *d, *e, ...;"!
 854         const string&amp; str;
 855       </CODE>
 856       <CODE class="bad">
 857         char * c;  // Bad - spaces on both sides of *
 858         const string &amp; str;  // Bad - spaces on both sides of &amp;
 859       </CODE>
 860       <P>
 861         You should do this consistently within a single file,
 862         so, when modifying an existing file, use the style in that file.
 863       </P>
 864
 865     <H3>Boolean Expressions</H3>
 866       <SUMMARY>
 867         When you have a boolean expression that is long, be consistent in
 868         how you break up the lines.
 869       </SUMMARY>
 870       <P>
 871         In this example, the logical AND operator is always at the end
 872         of the lines:
 873       </P>
 874       <CODE class="good">
 875         if( this_one_thing &gt; this_other_thing &amp;&amp;
 876             a_third_thing == a_fourth_thing &amp;&amp;
 877             yet_another &amp;&amp; last_one )
 878         {
 879           ...
 880         }
 881       </CODE>
 882
 883     <H3>Return Values</H3>
 884       <SUMMARY>
 885         Do not needlessly surround the <code>return</code> expression with parentheses.
 886       </SUMMARY>
 887       <CODE class="good">
 888         return result;                  // No parentheses in the simple case.
 889         return ( some_long_condition &amp;&amp;  // Parentheses ok to make a complex
 890                  another_condition );     //     expression more readable.
 891       </CODE>
 892       <CODE class="bad">
 893         return (value);                // You wouldn't write var = (value);
 894         return(result);                // return is not a function!
 895       </CODE>
 896     <H3>Variable and Array Initialization</H3>
 897       <SUMMARY>
 898         Your choice of <code>=</code> or <code>()</code>.
 899       </SUMMARY>
 900       <P>
 901         You may choose between <code>=</code> and <code>()</code>; the
 902         following are all correct:
 903       </P>
 904       <CODE class="good">
 905         int x = 3;
 906         int x( 3 );
 907         string name( "Some Name" );
 908         string name = "Some Name";
 909       </CODE>
 910
 911     <H3>Preprocessor Directives</H3>
 912       <SUMMARY>
 913         Preprocessor directives should not be indented but should
 914         instead start at the beginning of the line.
 915       </SUMMARY>
 916       <P>
 917         Even when pre-processor directives are within the body of
 918         indented code, the directives should start at the beginning of
 919         the line.
 920       </P>
 921       <CODE class="good">
 922         // Good - directives at beginning of line
 923           if( lopsided_score )
 924           {
 925         #if DISASTER_PENDING      // Correct -- Starts at beginning of line
 926             DropEverything();
 927         #endif
 928             BackToNormal();
 929           }
 930       </CODE>
 931       <CODE class="bad">
 932         // Bad - indented directives
 933           if( lopsided_score )
 934           {
 935             #if DISASTER_PENDING  // Wrong!  The "#if" should be at beginning of line
 936             DropEverything();
 937             #endif                // Wrong!  Do not indent "#endif"
 938             BackToNormal();
 939           }
 940       </CODE>
 941
 942   </ARTICLE>
 943
 944   <P>Thats all folks, if you read this far you are now all equipped to write good code :) !! </P>
 945
 946 </BODY>
 947 </HTML>