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 a 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         CamelCase with a leading capital letter, with no underscores. Enumerated type constants use the same convention as class constants, i.e. all uppercase with underscores.
 189         For example:
 190       </p>
 191       <CODE class="good">
 192         // classes and structs
 193         class UrlTable { ... };
 194         class UrlTableTester { ... };
 195         struct UrlTableProperties { ... };
 196
 197         // typedefs
 198         typedef hash_map<UrlTableProperties *, string> PropertiesMap;
 199
 200         // enums
 201         enum UrlTableErrors
 202         {
 203           OK = 0,
 204           OUT_OF_MEMORY = 1,
 205           MALFORMED_INPUT = 2,
 206         }
 207       </CODE>
 208     </ARTICLE>
 209   </ARTICLE>
 210
 211   <ARTICLE>
 212     <H2>Variable Names</H2>
 213     <SUMMARY>
 214       Variable names should use camel case, with an initial lower case letter.
 215       Local variable names start with a lowercase letter. 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       Avoid underscore characters in mixed case names.
 220       Constants should be all upper case, with underscores between words.
 221       Global variables should be avoided, however, 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         void SomeFunction()
 230         {
 231           string tableName;  // OK - starts lowercase
 232           string tablename;  // OK - all lowercase.
 233         }
 234       </CODE>
 235       <CODE class="bad">
 236         string TableName;   // Bad - starts with capital.
 237       </CODE>
 238       <CODE class="good">
 239         class Foo
 240         {
 241         public:
 242           string mTable;     // OK
 243           string mTableName; // OK.
 244         };
 245       </CODE>
 246       <CODE class="good">
 247         struct Foo
 248         {
 249           string table;     // OK
 250           string tableName; // OK.
 251         };
 252       </CODE>
 253       <CODE class="good">
 254         const int DAYS_IN_A_WEEK = 7;
 255       </CODE>
 256       <CODE class="bad">
 257         const int DaysInAWeek = 7; // Bad - constants should not use camel case.
 258         const int DAYSINAWEEK = 7; // Bad - without underscore, words run together.
 259       </CODE>
 260     </ARTICLE>
 261   </ARTICLE>
 262
 263   <ARTICLE>
 264     <H2>Function Names</H2>
 265     <SUMMARY>
 266       Regular function names are written in camel case starting with a
 267       capital letter and no underscores; accessors and mutators match
 268       the name of the variable with Get or Set as prefix.
 269     </SUMMARY>
 270     <H3>Examples <input type="button" value="Hide" onclick="toggleVisibility( this, 'function_name_examples' );"/></H3>
 271     <ARTICLE class="detail" id="function_name_examples">
 272       <CODE class="good">
 273         void MyExcitingFunction();
 274         void MyExcitingMethod();
 275
 276         class MyClass
 277         {
 278         public:
 279           ...
 280           int GetNumEntries() const { return mNumEntries; }
 281           void SetNumEntries( int numEntries ) { mNumEntries = numEntries; }
 282
 283         private:
 284           int mNumEntries;
 285         };
 286       </CODE>
 287
 288       <CODE class="bad">
 289         void my_boring_function(); // bad - uses underscores and no camel case.
 290       </CODE>
 291
 292     </ARTICLE>
 293   </ARTICLE>
 294
 295   <ARTICLE>
 296     <H2>Macro Names</H2>
 297     <SUMMARY>
 298       Macros should not be used for programming, code should always be readable without preprocessor.
 299       Only allowed cases for macros are include guards, debug tracing and compile time feature flags
 300       <b>inside</b> .cpp files when no other variation mechanism is not possible. Always prefer variation
 301       through design and template mechanisms rather than <i>#define</i>.
 302       If you need to use macros, they're like this: <code>MY_MACRO_THAT_SCARES_SMALL_CHILDREN</code>.
 303     </SUMMARY>
 304     <H3>Examples <input type="button" value="Hide" onclick="toggleVisibility( this, 'macro_name_examples' );"/></H3>
 305     <ARTICLE class="detail" id="macro_name_examples">
 306       <CODE class="good">
 307         #define DEBUG_TRACE( __FILE__, __LINE__ ) ...
 308         #ifndef __ACTOR_H__
 309         #define __ACTOR_H__
 310         ...
 311         #endif // __ACTOR_H__
 312       </CODE>
 313     </ARTICLE>
 314   </ARTICLE>
 315
 316 <H1>Comments</H1>
 317   <SUMMARY>
 318     Comments are absolutely vital to keeping our code readable.
 319     The following rules describe what you should comment and where.
 320     But remember: while comments are very important, the best code is self-documenting.
 321     Giving sensible names to types and variables is much better than using obscure
 322     names that you must then explain through comments.
 323     When writing your comments, write for your audience: the next
 324     contributor who will need to understand your code.
 325   </SUMMARY>
 326   <H2>Comment Rules <input type="button" value="Hide" onclick="toggleVisibility( this, 'comments_details' );"/></H2>
 327   <ARTICLE class="detail" id="comments_details">
 328     <H3>Comment Style</H3>
 329       <SUMMARY>
 330         API documentation must use doxygen comments:   /** */ or /// <BR>
 331         Internal comments can use <CODE>//</CODE> or <CODE>/* */</CODE> syntax, as long
 332         as you are consistent.
 333       </SUMMARY>
 334     <H3>File Comments</H3>
 335       <SUMMARY>
 336         Start each header file with a guard macro.<BR>
 337         This should match the name of the class which is defined in the file,
 338         including the namespace.<BR>
 339         For example, a class in the Dali namespace called Actor would have the guard:<BR><BR> __DALI_ACTOR_H__<BR><BR>
 340         An Actor class in the Dali::Internal namespace would have the guard:<BR><BR> __DALI_INTERNAL_ACTOR_H__<BR><BR>
 341         The copyright & legal notice should follow the guard macro (inside the #ifdef), since this will improve build times.<BR><BR>
 342         Start each source file with the copyright & legal notice.
 343       </SUMMARY>
 344     <H3>Class Comments</H3>
 345       <SUMMARY>
 346         Every class definition should have an accompanying comment that
 347         describes what it is for and how it should be used. It should have
 348         a brief description, followed by a newline and a broader description.
 349       </SUMMARY>
 350       <CODE class="good">
 351         /**
 352          * @brief Iterates over the contents of a GargantuanTable.
 353          *
 354          * Example usage:
 355          *    GargantuanTableIterator* iter = table-&gt;NewIterator();
 356          *    for( iter-&gt;Seek("foo"); !iter-&gt;done(); iter-&gt;Next() )
 357          *    {
 358          *      process( iter-&gt;key(), iter-&gt;value() );
 359          *    }
 360          *    delete iter;
 361          */
 362         class GargantuanTableIterator
 363         {
 364           ...
 365         };
 366       </CODE>
 367       <P>
 368         Document the synchronization assumptions the class makes, if
 369         any. If an instance of the class can be accessed by multiple
 370         threads, take extra care to document the rules and invariants
 371         surrounding multithreaded use.
 372       </P>
 373     <H3>Function Comments</H3>
 374       <SUMMARY>
 375         Every function declaration in a header file must have a brief comment
 376         that describes what the function does, followed by a newline. It may
 377         be followed by a detailed description on how to use it.
 378         These comments should be descriptive ("Opens the file") rather than
 379         imperative ("Open the file"); the
 380         comment describes the function, it does not tell the function what to do.
 381         Each parameter must be documented, as must any return value.
 382       </SUMMARY>
 383       <P>
 384         Types of things to mention in comments at the function
 385         declaration:
 386       </P>
 387       <UL>
 388         <LI> What the inputs and outputs are.</LI>
 389         <LI> For class member functions:  whether the object
 390               remembers reference arguments beyond the
 391               duration of the method call, and whether it will
 392               free them or not. </LI>
 393         <LI> If the function allocates memory that the caller
 394               must free. </LI>
 395         <LI> Whether any of the arguments can be <CODE>NULL</CODE> </LI>
 396         <LI> If there are any performance implications of how a function is used.</LI>
 397         <LI> If the function is re-entrant.  What are its synchronization assumptions? </LI>
 398       </UL>
 399         <CODE class="good">
 400           /**
 401            * @brief Get the iterator for this data table.
 402            *
 403            * It is the client's responsibility to delete the iterator,
 404            * and it must not use the iterator once the GargantuanTable object
 405            * on which the iterator was created has been deleted.
 406            *
 407            * The iterator is initially positioned at the beginning of the table.
 408            *
 409            * This method is equivalent to:
 410            *    Iterator* iter = table->NewIterator();
 411            *    iter->Seek( "" );
 412            *    return iter;
 413            * If you are going to immediately seek to another place in the
 414            * returned iterator, it will be faster to use NewIterator()
 415            * and avoid the extra seek.
 416            * @return an iterator for this table.
 417            */
 418           Iterator* GetIterator() const;
 419         </CODE>
 420         <P>
 421           When commenting constructors and destructors, remember that
 422           the person reading your code knows what constructors and
 423           destructors are for, so comments that just say something like
 424           "destroys this object" are not useful.
 425         </P>
 426     <H3>Variable Comments</H3>
 427       <SUMMARY>
 428         In general the actual name of the variable should be descriptive
 429         enough to give a good idea of what the variable is used for. In
 430         certain cases, more comments are required - use Doxygen formatting.
 431       </SUMMARY>
 432       <CODE class="good">
 433         private:
 434           /**
 435            * @brief Keeps track of the total number of entries in the table.
 436            *
 437            * Used to ensure we do not go over the limit. -1 means
 438            * that we don't yet know how many entries the table has.
 439            */
 440           int mNumTotalEntries;
 441
 442           float mDuration; ///< Duration in seconds.
 443       </CODE>
 444
 445     <H3> Duplicate documentation</H3>
 446     <SUMMARY>
 447         Try to avoid duplicate documentation by using the @copydoc command.
 448     </SUMMARY>
 449     <P>
 450        @copydoc copies a documentation block from the object specified by
 451        link-object and pastes it at the location of the command.
 452        This command can be useful to avoid cases where a documentation block
 453        would otherwise have to be duplicated or it can be used to extend the
 454        documentation of an inherited member.
 455     </P>
 456     <CODE class="good">
 457      /**
 458       * @copydoc MyClass::myfunction()
 459       * More documentation.
 460       */
 461     </CODE>
 462      <P>
 463        If the member is overloaded, you should specify the argument types
 464        explicitly (without spaces!), like in the following:
 465      </P>
 466      <CODE class="good">
 467       /** @copydoc MyClass::myfunction(type1,type2) */
 468      </CODE>
 469     <H3>Punctuation, Spelling and Grammar</H3>
 470       <SUMMARY>
 471         Pay attention to punctuation, spelling, and grammar; it is
 472         easier to read well-written comments than badly written ones.
 473       </SUMMARY>
 474       <P>
 475         Comments should usually be written as complete
 476         sentences with proper capitalization and periods at the end.
 477         Shorter comments, such as comments at the end of a line of
 478         code, can sometimes be less formal, but you should be
 479         consistent with your style.  Complete sentences are more
 480         readable, and they provide some assurance that the comment is
 481         complete and not an unfinished thought.
 482       </P>
 483     <H3>TODO Comments</H3>
 484       <SUMMARY>
 485         Use <code>TODO</code> comments for code that is temporary, a
 486         short-term solution, or good-enough but not perfect.
 487       </SUMMARY>
 488     <H3>Deprecation Comments</H3>
 489       <SUMMARY>
 490         Mark deprecated interface points with <code>@deprecated</code> comments.
 491       </SUMMARY>
 492   </ARTICLE>
 493
 494 <H1>Formatting</H1>
 495
 496   <SUMMARY>
 497     A project is much easier to follow if everyone uses the same style.
 498     It is important that all contributors follow the style rules so that
 499     they can all read and understand everyone's code easily.
 500   </SUMMARY>
 501
 502   <H2>Formatting Rules <input type="button" value="Hide" onclick="toggleVisibility( this, 'formatting_rules' );"/></H2>
 503   <ARTICLE class="detail" id="formatting_rules">
 504     <H3>Basic Rules</H3>
 505     <UL>
 506       <LI>Use only spaces, and indent 2 spaces at a time</LI>
 507       <LI>Avoid unnecessary trailing whitescape</LI>
 508       <LI>Avoid overly long lines, modern screens and editors can handle upto 120 characters</LI>
 509       <LI>Use UTF-8 formatting for non-ASCII characters</LI>
 510       <LI>Anything enclosed in parentheses should also have a space inside the parentheses. </LI>
 511       <LI>Braces must each be in a line on their own.</LI>
 512     </UL>
 513     <P>
 514     Hex encoding is also OK, and encouraged where it enhances
 515     readability &#8212; for example, <code>"\xEF\xBB\xBF"</code> is the
 516     Unicode zero-width no-break space character, which would be
 517     invisible if included in the source as straight UTF-8.
 518     </P>
 519
 520     <H3>Class Format</H3>
 521       <SUMMARY>
 522         Sections in <code>public</code>, <code>protected</code> and
 523         <code>private</code> order.
 524         Typedefs and Enums first, Constructor(s) & Destructors & public API next, then virtual methods and implementation details last.
 525       </SUMMARY>
 526       <CODE class="good">
 527         /**
 528          * @brief Class purpose.
 529          *
 530          * Long description.
 531          */
 532         class MyClass : public Base
 533         {
 534         public: // API
 535
 536           /**
 537            * @brief Short description.
 538            *
 539            * Documentation
 540            */
 541           MyClass();  // 2 space indent.
 542
 543           /**
 544            * @brief Short description.
 545            *
 546            * @param[in] var Description
 547            */
 548           explicit MyClass( int var );
 549
 550           /**
 551            * @brief Short description.
 552            *
 553            * Documentation
 554            */
 555           virtual ~MyClass();
 556
 557           /**
 558            * @brief Short description.
 559            *
 560            * Documentation
 561            */
 562           void SomeFunction();
 563
 564           /**
 565            * @brief Short description.
 566            *
 567            * Documentation
 568            */
 569           void SomeFunctionThatDoesNothing();
 570
 571           /**
 572            * @brief Short description.
 573            *
 574            * Documentation
 575            * @param[in] var Parameter description
 576            */
 577           void SetSomeVar( int var )
 578
 579           /**
 580            * @brief Short description.
 581            *
 582            * Documentation.
 583            * @return value description.
 584            */
 585           int GetSomeVar() const
 586
 587         private: // Implementation
 588
 589           MyClass( MyClass& aRHs ); ///< no copying
 590           MyClass& operator=( const MyClass& aRHs );  ///< no copying.
 591           bool SomeInternalFunction();
 592
 593           int mSomeVar;       ///< short description.
 594           int mSomeOtherVar;  ///< short description.
 595         };
 596       </CODE>
 597
 598     <H3>Constructor Initializer Lists</H3>
 599       <SUMMARY>
 600         Constructor initializer lists can be all on one line or with subsequent lines indented.
 601         Always initialize things in declaration order, base class first!!
 602       </SUMMARY>
 603       <CODE class="good">
 604         // When it all fits on one line:
 605         MyClass::MyClass( int var ) : Base( var), mSomeVar( var ), mSomeOtherVar( var + 1 )
 606         {
 607         }
 608
 609         // When it requires multiple lines, indent, putting the colon on
 610         // the first initializer line:
 611         MyClass::MyClass( int var )
 612         : Base( var ),
 613           mSomeVar( var ),
 614           mSomeOtherVar( var + 1 )
 615         {
 616           DoSomething();
 617         }
 618       </CODE>
 619
 620     <H3>Namespace Formatting</H3>
 621       <SUMMARY>
 622         The contents of namespaces are not indented.
 623       </SUMMARY>
 624       <CODE class="good">
 625         namespace
 626         {
 627
 628         void Foo()
 629         {  // Correct.  No extra indentation within namespace.
 630           ...
 631         }
 632
 633         }  // namespace
 634       </CODE>
 635       <P>
 636         When declaring nested namespaces, put each namespace on its own line.
 637       </P>
 638       <CODE class="good">
 639         /**
 640          * @brief description of namespace
 641          */
 642         namespace Foo
 643         {
 644
 645         /**
 646          * @brief description of namespace
 647          */
 648         namespace Bar
 649         {
 650       </CODE>
 651
 652     <H3>Function Declarations and Definitions</H3>
 653       <SUMMARY>
 654         Return type on the same line as function name, parameters on the same line if they fit.
 655         All parameters should be named, with identical names in the declaration and definition.
 656       </SUMMARY>
 657       <CODE class="good">
 658         ReturnType ClassName::FunctionName( Type parameterName1, Type parameterName2 )
 659         {
 660           DoSomething();
 661         }
 662       </CODE>
 663       <P>
 664         If you have too much text to fit on one line:
 665       </P>
 666       <CODE class="good">
 667         ReturnType ClassName::ReallyLongFunctionName( Type parameterName1,
 668                                                       Type parameterName2,
 669                                                       Type parameterName3 )
 670         {
 671           DoSomething();
 672         }
 673       </CODE>
 674       <P>
 675         or if you cannot fit even the first parameter:
 676       </P>
 677       <CODE class="good">
 678         ReturnType LongClassName::ReallyReallyReallyLongFunctionName(
 679           Type parameterName1,  // 2 space indent
 680           Type parameterName2,
 681           Type parameterName3 )
 682         {
 683           DoSomething();  // 2 space indent
 684           ...
 685         }
 686       </CODE>
 687       <P>
 688         <code>const</code> keyword should be on the same line as the last parameter:
 689       </P>
 690       <CODE class="good">
 691         // Everything in this function signature fits on a single line
 692         ReturnType FunctionName( Type parameter ) const
 693         {
 694           ...
 695         }
 696
 697         // This function signature requires multiple lines, but
 698         // the const keyword is on the line with the last parameter.
 699         ReturnType ReallyLongFunctionName( Type parameter1,
 700                                            Type parameter2 ) const
 701         {
 702           ...
 703         }
 704       </CODE>
 705       <P>
 706         If some parameters are unused, comment out the variable name in the function definition:
 707       </P>
 708       <CODE class="good">
 709         // Always have named parameters in interfaces.
 710         class Shape
 711         {
 712         public:
 713           virtual void Rotate( double radians ) = 0;
 714         }
 715
 716         // Always have named parameters in the declaration.
 717         class Circle : public Shape
 718         {
 719         public:
 720           virtual void Rotate( double radians );
 721         }
 722
 723         // Comment out unused named parameters in definitions.
 724         void Circle::Rotate( double /*radians*/ )
 725         {
 726         }
 727       </CODE>
 728       <CODE class="bad">
 729         // Bad - if someone wants to implement later, it's not clear what the
 730         // variable means.
 731         void Circle::Rotate( double )
 732         {
 733         }
 734       </CODE>
 735
 736     <H3>Function Calls</H3>
 737       <SUMMARY>
 738         On one line if it fits; otherwise, wrap arguments at the parenthesis. Put one space inside the parentheses, none outside.
 739       </SUMMARY>
 740       <BODY>
 741         <CODE class="good">
 742           bool retval = DoSomething( argument1, argument2, argument3 );
 743         </CODE>
 744         <P>
 745           If the arguments do not all fit on one line, they should be
 746           broken up onto multiple lines, with each subsequent line
 747           aligned with the first argument:
 748         </P>
 749         <CODE class="good">
 750           bool retval = DoSomething( aVeryVeryVeryVeryLongArgument1,
 751                                      argument2, argument3 );
 752         </CODE>
 753         <P>
 754           If the function has many arguments, consider having one per
 755           line if this makes the code more readable:
 756         </P>
 757         <CODE class="good">
 758           bool retval = DoSomething( argument1,
 759                                      argument2,
 760                                      argument3,
 761                                      argument4 );
 762         </CODE>
 763         <P>
 764           If the function signature is so long that it cannot fit,
 765           place all arguments on subsequent lines:
 766         </P>
 767         <CODE class="good">
 768           if( ... )
 769           {
 770             DoSomethingThatRequiresALongFunctionName(
 771               aVeryLongArgument1,  // indent
 772               argument2,
 773               argument3,
 774               argument4 );
 775           }
 776         </CODE>
 777
 778     <H3>Conditionals</H3>
 779       <SUMMARY>
 780         The <code>if</code> statement should be followed only by the conditional, with a space inside the parentheses, not outside. The following clause must always be surrounded by braces on separate lines.
 781         The <code>else</code> keyword belongs on its own line, and the following clause must always be
 782         surrounded by braces.
 783       </SUMMARY>
 784       <CODE class="good">
 785         if( condition ) // space inside parentheses
 786         {
 787           ...
 788         }
 789         else
 790         {
 791           ...
 792         }
 793       </CODE>
 794       <CODE class="bad">
 795         if(condition)     // Bad - space missing inside parentheses
 796         if(condition){    // Doubly bad. Mis-aligned parentheses are harder to read.
 797       </CODE>
 798       <P>
 799         Must always have curly braces for the clauses, and they must always be on a line
 800         on their own:
 801       </P>
 802       <CODE class="good">
 803         if( condition )
 804         {
 805           DoSomething();  // 2 space indent.
 806         }
 807         else
 808         {
 809           DoSomethingElse(); // 2 space indent.
 810         }
 811       </CODE>
 812
 813     <H3>Loops and Switch Statements</H3>
 814       <SUMMARY>
 815         Switch statements use braces for blocks. Empty loop bodies must use
 816         <code>{}</code> or <code>continue</code>.
 817         Switch statements should always have a <code>default</code> case
 818         unless they switch on an <code>enum</code> type,
 819         for which the compiler will ensure all values are handled.
 820
 821         If the default case should never execute, simply <code>assert</code>.
 822         Put one space inside the parentheses, none outside.
 823       </SUMMARY>
 824       <P>
 825         <code>case</code> blocks in <code>switch</code> statements must have
 826         curly braces.
 827         They should be placed as shown below.
 828       </P>
 829
 830       <CODE class="good">
 831         switch( var )
 832         {
 833           case 0: // 2 space indent
 834           {
 835             ...      // 2 space indent
 836             break;
 837           }
 838           case 1:
 839           {
 840             ...
 841             break;
 842           }
 843           default:
 844           {
 845             DALI_ASSERT_ALWAYS( false );
 846           }
 847         }
 848       </CODE>
 849       <P>
 850         Empty loop bodies should use <code>{}</code> or
 851         <code>continue</code>, but not a single semicolon.
 852       </P>
 853       <CODE class="good">
 854         while( condition )
 855         {
 856           // Repeat test until it returns false.
 857         }
 858
 859         for( int i = 0; i < someNumber; ++i )
 860         {
 861         }  // Good - empty body, clearly separated.
 862
 863         while( condition )
 864           continue;  // Good - continue indicates no logic.
 865
 866       </CODE>
 867       <CODE class="bad">
 868         while( condition );  // Bad - looks like part of do/while loop.
 869       </CODE>
 870     <H3>Pointer and Reference Expressions</H3>
 871       <SUMMARY>
 872         No spaces around period or arrow.  Pointer operators do not have trailing spaces.
 873       </SUMMARY>
 874       <P>
 875         The following are examples of correctly-formatted pointer and
 876         reference expressions:
 877       </P>
 878       <CODE class="good">
 879         x = *p;
 880         p = &amp;x;
 881         x = r.y;
 882         x = r-&gt;y;
 883       </CODE>
 884       <P>
 885         When declaring a pointer variable or argument, you may place
 886         the asterisk adjacent to either the type or to the variable
 887         name, however, placing with the type is preferred.
 888       </P>
 889       <CODE class="good">
 890         // These are fine, space preceding.
 891         char *c;
 892         const string &amp;str;
 893
 894         // These are fine, space following.
 895         char* c;    // but remember to do each variable on its own line or "char* c, *d, *e, ...;"!
 896         const string&amp; str;
 897       </CODE>
 898       <CODE class="bad">
 899         char * c;  // Bad - spaces on both sides of *
 900         const string &amp; str;  // Bad - spaces on both sides of &amp;
 901       </CODE>
 902       <P>
 903         You should do this consistently within a single file,
 904         so, when modifying an existing file, use the style in that file.
 905       </P>
 906
 907     <H3>Boolean Expressions</H3>
 908       <SUMMARY>
 909         When you have a boolean expression that is long, be consistent in
 910         how you break up the lines.
 911       </SUMMARY>
 912       <P>
 913         In this example, the logical AND operator is always at the end
 914         of the lines:
 915       </P>
 916       <CODE class="good">
 917         if( thisOneThing &gt; thisOtherThing &amp;&amp;
 918             aThirdThing == aFourthThing &amp;&amp;
 919             yetAnother &amp;&amp; lastOne )
 920         {
 921           ...
 922         }
 923       </CODE>
 924
 925     <H3>Return Values</H3>
 926       <SUMMARY>
 927         Do not needlessly surround the <code>return</code> expression with parentheses.
 928       </SUMMARY>
 929       <CODE class="good">
 930         return result;                   // No parentheses in the simple case.
 931         return ( someLongCondition &amp;&amp;    // Parentheses ok to make a complex
 932                  anotherCondition );     //     expression more readable.
 933       </CODE>
 934       <CODE class="bad">
 935         return (value);                // You wouldn't write var = (value);
 936         return(result);                // return is not a function!
 937       </CODE>
 938     <H3>Variable and Array Initialization</H3>
 939       <SUMMARY>
 940         Your choice of <code>=</code> or <code>()</code>.
 941       </SUMMARY>
 942       <P>
 943         You may choose between <code>=</code> and <code>()</code>; the
 944         following are all correct:
 945       </P>
 946       <CODE class="good">
 947         int x = 3;
 948         int x( 3 );
 949         string name( "Some Name" );
 950         string name = "Some Name";
 951       </CODE>
 952
 953     <H3>Preprocessor Directives</H3>
 954       <SUMMARY>
 955         Preprocessor directives should not be indented but should
 956         instead start at the beginning of the line.
 957       </SUMMARY>
 958       <P>
 959         Even when pre-processor directives are within the body of
 960         indented code, the directives should start at the beginning of
 961         the line.
 962       </P>
 963       <CODE class="good">
 964         // Good - directives at beginning of line
 965           if( lopsidedScore )
 966           {
 967         #if DISASTER_PENDING      // Correct -- Starts at beginning of line
 968             DropEverything();
 969         #endif
 970             BackToNormal();
 971           }
 972       </CODE>
 973       <CODE class="bad">
 974         // Bad - indented directives
 975           if( lopsidedScore )
 976           {
 977             #if DISASTER_PENDING  // Wrong!  The "#if" should be at beginning of line
 978             DropEverything();
 979             #endif                // Wrong!  Do not indent "#endif"
 980             BackToNormal();
 981           }
 982       </CODE>
 983
 984   </ARTICLE>
 985
 986   <P>Thats all folks, if you read this far you are now all equipped to write good code :) !! </P>
 987
 988 </BODY>
 989 </HTML>