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     <H3>Doxygen Tags</H3>
 493       <SUMMARY>
 494        The following order should be followed when using doxygen tags for functions, classes, structs etc.
 495       </SUMMARY>
 496       <CODE class="good">
 497        /**
 498         * @deprecated DALi X.X.X    Mandatory, if applicable    // Version deprecated and alternative
 499         * @brief                    Mandatory                   // Explain the API briefly
 500         * @details                  Optional                    // Explain the API in more detail. Use this tag or add more
 501         *                                                       // information after a blank line following the @brief
 502         * @since DALi X.X.X         Mandatory                   // Version added
 503         * @param[in]                Mandatory, if applicable    // In Parameter list
 504         * @param[out]               Mandatory, if applicable    // Out Parameter list
 505         * @param[in,out]            Mandatory, if applicable    // In/Out Parameter list
 506         * @return                   Mandatory, if applicable    // Return value
 507         * @pre                      Optional                    // Pre-condition
 508         * @post                     Optional                    // Post-condition
 509         * @note                     Optional                    // Any notes that apply
 510         * @see                      Optional                    // Other related APIs
 511         */
 512       </CODE>
 513       <SUMMARY>
 514        Where X.X.X is the next release version (ensure you're patch gets merged before the release).
 515       </SUMMARY>
 516   </ARTICLE>
 517
 518 <H1>Formatting</H1>
 519
 520   <SUMMARY>
 521     A project is much easier to follow if everyone uses the same style.
 522     It is important that all contributors follow the style rules so that
 523     they can all read and understand everyone's code easily.
 524   </SUMMARY>
 525
 526   <H2>Formatting Rules <input type="button" value="Hide" onclick="toggleVisibility( this, 'formatting_rules' );"/></H2>
 527   <ARTICLE class="detail" id="formatting_rules">
 528     <H3>Basic Rules</H3>
 529     <UL>
 530       <LI>Use only spaces, and indent 2 spaces at a time</LI>
 531       <LI>Avoid unnecessary trailing whitescape</LI>
 532       <LI>Avoid overly long lines, modern screens and editors can handle upto 120 characters</LI>
 533       <LI>Use UTF-8 formatting for non-ASCII characters</LI>
 534       <LI>Anything enclosed in parentheses should also have a space inside the parentheses. </LI>
 535       <LI>Braces must each be in a line on their own.</LI>
 536     </UL>
 537     <P>
 538     Hex encoding is also OK, and encouraged where it enhances
 539     readability &#8212; for example, <code>"\xEF\xBB\xBF"</code> is the
 540     Unicode zero-width no-break space character, which would be
 541     invisible if included in the source as straight UTF-8.
 542     </P>
 543
 544     <H3>Class Format</H3>
 545       <SUMMARY>
 546         Sections in <code>public</code>, <code>protected</code> and
 547         <code>private</code> order.
 548         Typedefs and Enums first, Constructor(s) & Destructors & public API next, then virtual methods and implementation details last.
 549       </SUMMARY>
 550       <CODE class="good">
 551         /**
 552          * @brief Class purpose.
 553          *
 554          * Long description.
 555          */
 556         class MyClass : public Base
 557         {
 558         public: // API
 559
 560           /**
 561            * @brief Short description.
 562            *
 563            * Documentation
 564            */
 565           MyClass();  // 2 space indent.
 566
 567           /**
 568            * @brief Short description.
 569            *
 570            * @param[in] var Description
 571            */
 572           explicit MyClass( int var );
 573
 574           /**
 575            * @brief Short description.
 576            *
 577            * Documentation
 578            */
 579           virtual ~MyClass();
 580
 581           /**
 582            * @brief Short description.
 583            *
 584            * Documentation
 585            */
 586           void SomeFunction();
 587
 588           /**
 589            * @brief Short description.
 590            *
 591            * Documentation
 592            */
 593           void SomeFunctionThatDoesNothing();
 594
 595           /**
 596            * @brief Short description.
 597            *
 598            * Documentation
 599            * @param[in] var Parameter description
 600            */
 601           void SetSomeVar( int var )
 602
 603           /**
 604            * @brief Short description.
 605            *
 606            * Documentation.
 607            * @return value description.
 608            */
 609           int GetSomeVar() const
 610
 611         private: // Implementation
 612
 613           MyClass( MyClass& aRHs ); ///< no copying
 614           MyClass& operator=( const MyClass& aRHs );  ///< no copying.
 615           bool SomeInternalFunction();
 616
 617           int mSomeVar;       ///< short description.
 618           int mSomeOtherVar;  ///< short description.
 619         };
 620       </CODE>
 621
 622     <H3>Constructor Initializer Lists</H3>
 623       <SUMMARY>
 624         Constructor initializer lists can be all on one line or with subsequent lines indented.
 625         Always initialize things in declaration order, base class first!!
 626       </SUMMARY>
 627       <CODE class="good">
 628         // When it all fits on one line:
 629         MyClass::MyClass( int var ) : Base( var), mSomeVar( var ), mSomeOtherVar( var + 1 )
 630         {
 631         }
 632
 633         // When it requires multiple lines, indent, putting the colon on
 634         // the first initializer line:
 635         MyClass::MyClass( int var )
 636         : Base( var ),
 637           mSomeVar( var ),
 638           mSomeOtherVar( var + 1 )
 639         {
 640           DoSomething();
 641         }
 642       </CODE>
 643
 644     <H3>Namespace Formatting</H3>
 645       <SUMMARY>
 646         The contents of namespaces are not indented.
 647       </SUMMARY>
 648       <CODE class="good">
 649         namespace
 650         {
 651
 652         void Foo()
 653         {  // Correct.  No extra indentation within namespace.
 654           ...
 655         }
 656
 657         }  // namespace
 658       </CODE>
 659       <P>
 660         When declaring nested namespaces, put each namespace on its own line.
 661       </P>
 662       <CODE class="good">
 663         /**
 664          * @brief description of namespace
 665          */
 666         namespace Foo
 667         {
 668
 669         /**
 670          * @brief description of namespace
 671          */
 672         namespace Bar
 673         {
 674       </CODE>
 675
 676     <H3>Function Declarations and Definitions</H3>
 677       <SUMMARY>
 678         Return type on the same line as function name, parameters on the same line if they fit.
 679         All parameters should be named, with identical names in the declaration and definition.
 680       </SUMMARY>
 681       <CODE class="good">
 682         ReturnType ClassName::FunctionName( Type parameterName1, Type parameterName2 )
 683         {
 684           DoSomething();
 685         }
 686       </CODE>
 687       <P>
 688         If you have too much text to fit on one line:
 689       </P>
 690       <CODE class="good">
 691         ReturnType ClassName::ReallyLongFunctionName( Type parameterName1,
 692                                                       Type parameterName2,
 693                                                       Type parameterName3 )
 694         {
 695           DoSomething();
 696         }
 697       </CODE>
 698       <P>
 699         or if you cannot fit even the first parameter:
 700       </P>
 701       <CODE class="good">
 702         ReturnType LongClassName::ReallyReallyReallyLongFunctionName(
 703           Type parameterName1,  // 2 space indent
 704           Type parameterName2,
 705           Type parameterName3 )
 706         {
 707           DoSomething();  // 2 space indent
 708           ...
 709         }
 710       </CODE>
 711       <P>
 712         <code>const</code> keyword should be on the same line as the last parameter:
 713       </P>
 714       <CODE class="good">
 715         // Everything in this function signature fits on a single line
 716         ReturnType FunctionName( Type parameter ) const
 717         {
 718           ...
 719         }
 720
 721         // This function signature requires multiple lines, but
 722         // the const keyword is on the line with the last parameter.
 723         ReturnType ReallyLongFunctionName( Type parameter1,
 724                                            Type parameter2 ) const
 725         {
 726           ...
 727         }
 728       </CODE>
 729       <P>
 730         If some parameters are unused, comment out the variable name in the function definition:
 731       </P>
 732       <CODE class="good">
 733         // Always have named parameters in interfaces.
 734         class Shape
 735         {
 736         public:
 737           virtual void Rotate( double radians ) = 0;
 738         }
 739
 740         // Always have named parameters in the declaration.
 741         class Circle : public Shape
 742         {
 743         public:
 744           virtual void Rotate( double radians );
 745         }
 746
 747         // Comment out unused named parameters in definitions.
 748         void Circle::Rotate( double /*radians*/ )
 749         {
 750         }
 751       </CODE>
 752       <CODE class="bad">
 753         // Bad - if someone wants to implement later, it's not clear what the
 754         // variable means.
 755         void Circle::Rotate( double )
 756         {
 757         }
 758       </CODE>
 759
 760     <H3>Function Calls</H3>
 761       <SUMMARY>
 762         On one line if it fits; otherwise, wrap arguments at the parenthesis. Put one space inside the parentheses, none outside.
 763       </SUMMARY>
 764       <BODY>
 765         <CODE class="good">
 766           bool retval = DoSomething( argument1, argument2, argument3 );
 767         </CODE>
 768         <P>
 769           If the arguments do not all fit on one line, they should be
 770           broken up onto multiple lines, with each subsequent line
 771           aligned with the first argument:
 772         </P>
 773         <CODE class="good">
 774           bool retval = DoSomething( aVeryVeryVeryVeryLongArgument1,
 775                                      argument2, argument3 );
 776         </CODE>
 777         <P>
 778           If the function has many arguments, consider having one per
 779           line if this makes the code more readable:
 780         </P>
 781         <CODE class="good">
 782           bool retval = DoSomething( argument1,
 783                                      argument2,
 784                                      argument3,
 785                                      argument4 );
 786         </CODE>
 787         <P>
 788           If the function signature is so long that it cannot fit,
 789           place all arguments on subsequent lines:
 790         </P>
 791         <CODE class="good">
 792           if( ... )
 793           {
 794             DoSomethingThatRequiresALongFunctionName(
 795               aVeryLongArgument1,  // indent
 796               argument2,
 797               argument3,
 798               argument4 );
 799           }
 800         </CODE>
 801
 802     <H3>Conditionals</H3>
 803       <SUMMARY>
 804         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.
 805         The <code>else</code> keyword belongs on its own line, and the following clause must always be
 806         surrounded by braces.
 807       </SUMMARY>
 808       <CODE class="good">
 809         if( condition ) // space inside parentheses
 810         {
 811           ...
 812         }
 813         else
 814         {
 815           ...
 816         }
 817       </CODE>
 818       <CODE class="bad">
 819         if(condition)     // Bad - space missing inside parentheses
 820         if(condition){    // Doubly bad. Mis-aligned parentheses are harder to read.
 821       </CODE>
 822       <P>
 823         Must always have curly braces for the clauses, and they must always be on a line
 824         on their own:
 825       </P>
 826       <CODE class="good">
 827         if( condition )
 828         {
 829           DoSomething();  // 2 space indent.
 830         }
 831         else
 832         {
 833           DoSomethingElse(); // 2 space indent.
 834         }
 835       </CODE>
 836
 837     <H3>Loops and Switch Statements</H3>
 838       <SUMMARY>
 839         Switch statements use braces for blocks. Empty loop bodies must use
 840         <code>{}</code> or <code>continue</code>.
 841         Switch statements should always have a <code>default</code> case
 842         unless they switch on an <code>enum</code> type,
 843         for which the compiler will ensure all values are handled.
 844
 845         If the default case should never execute, simply <code>assert</code>.
 846         Put one space inside the parentheses, none outside.
 847       </SUMMARY>
 848       <P>
 849         <code>case</code> blocks in <code>switch</code> statements must have
 850         curly braces.
 851         They should be placed as shown below.
 852       </P>
 853
 854       <CODE class="good">
 855         switch( var )
 856         {
 857           case 0: // 2 space indent
 858           {
 859             ...      // 2 space indent
 860             break;
 861           }
 862           case 1:
 863           {
 864             ...
 865             break;
 866           }
 867           default:
 868           {
 869             DALI_ASSERT_ALWAYS( false );
 870           }
 871         }
 872       </CODE>
 873       <P>
 874         Empty loop bodies should use <code>{}</code> or
 875         <code>continue</code>, but not a single semicolon.
 876       </P>
 877       <CODE class="good">
 878         while( condition )
 879         {
 880           // Repeat test until it returns false.
 881         }
 882
 883         for( int i = 0; i < someNumber; ++i )
 884         {
 885         }  // Good - empty body, clearly separated.
 886
 887         while( condition )
 888           continue;  // Good - continue indicates no logic.
 889
 890       </CODE>
 891       <CODE class="bad">
 892         while( condition );  // Bad - looks like part of do/while loop.
 893       </CODE>
 894     <H3>Pointer and Reference Expressions</H3>
 895       <SUMMARY>
 896         No spaces around period or arrow.  Pointer operators do not have trailing spaces.
 897       </SUMMARY>
 898       <P>
 899         The following are examples of correctly-formatted pointer and
 900         reference expressions:
 901       </P>
 902       <CODE class="good">
 903         x = *p;
 904         p = &amp;x;
 905         x = r.y;
 906         x = r-&gt;y;
 907       </CODE>
 908       <P>
 909         When declaring a pointer variable or argument, you may place
 910         the asterisk adjacent to either the type or to the variable
 911         name, however, placing with the type is preferred.
 912       </P>
 913       <CODE class="good">
 914         // These are fine, space preceding.
 915         char *c;
 916         const string &amp;str;
 917
 918         // These are fine, space following.
 919         char* c;    // but remember to do each variable on its own line or "char* c, *d, *e, ...;"!
 920         const string&amp; str;
 921       </CODE>
 922       <CODE class="bad">
 923         char * c;  // Bad - spaces on both sides of *
 924         const string &amp; str;  // Bad - spaces on both sides of &amp;
 925       </CODE>
 926       <P>
 927         You should do this consistently within a single file,
 928         so, when modifying an existing file, use the style in that file.
 929       </P>
 930
 931     <H3>Boolean Expressions</H3>
 932       <SUMMARY>
 933         When you have a boolean expression that is long, be consistent in
 934         how you break up the lines.
 935       </SUMMARY>
 936       <P>
 937         In this example, the logical AND operator is always at the end
 938         of the lines:
 939       </P>
 940       <CODE class="good">
 941         if( thisOneThing &gt; thisOtherThing &amp;&amp;
 942             aThirdThing == aFourthThing &amp;&amp;
 943             yetAnother &amp;&amp; lastOne )
 944         {
 945           ...
 946         }
 947       </CODE>
 948
 949     <H3>Return Values</H3>
 950       <SUMMARY>
 951         Do not needlessly surround the <code>return</code> expression with parentheses.
 952       </SUMMARY>
 953       <CODE class="good">
 954         return result;                   // No parentheses in the simple case.
 955         return ( someLongCondition &amp;&amp;    // Parentheses ok to make a complex
 956                  anotherCondition );     //     expression more readable.
 957       </CODE>
 958       <CODE class="bad">
 959         return (value);                // You wouldn't write var = (value);
 960         return(result);                // return is not a function!
 961       </CODE>
 962     <H3>Variable and Array Initialization</H3>
 963       <SUMMARY>
 964         Your choice of <code>=</code> or <code>()</code>.
 965       </SUMMARY>
 966       <P>
 967         You may choose between <code>=</code> and <code>()</code>; the
 968         following are all correct:
 969       </P>
 970       <CODE class="good">
 971         int x = 3;
 972         int x( 3 );
 973         string name( "Some Name" );
 974         string name = "Some Name";
 975       </CODE>
 976
 977     <H3>Preprocessor Directives</H3>
 978       <SUMMARY>
 979         Preprocessor directives should not be indented but should
 980         instead start at the beginning of the line.
 981       </SUMMARY>
 982       <P>
 983         Even when pre-processor directives are within the body of
 984         indented code, the directives should start at the beginning of
 985         the line.
 986       </P>
 987       <CODE class="good">
 988         // Good - directives at beginning of line
 989           if( lopsidedScore )
 990           {
 991         #if DISASTER_PENDING      // Correct -- Starts at beginning of line
 992             DropEverything();
 993         #endif
 994             BackToNormal();
 995           }
 996       </CODE>
 997       <CODE class="bad">
 998         // Bad - indented directives
 999           if( lopsidedScore )
1000           {
1001             #if DISASTER_PENDING  // Wrong!  The "#if" should be at beginning of line
1002             DropEverything();
1003             #endif                // Wrong!  Do not indent "#endif"
1004             BackToNormal();
1005           }
1006       </CODE>
1007
1008   </ARTICLE>
1009
1010   <P>Thats all folks, if you read this far you are now all equipped to write good code :) !! </P>
1011
1012 </BODY>
1013 </HTML>