drawElements Coding Guidelines

- -

"Always code as if the person who will maintain your code is a maniac serial killer that knows where you live."

- -

Table of Contents -
-

Introduction -

Goal and philosophy -
This document describes the drawElements coding style for C and C++ languages.
- -
The intention of the drawElements coding guidelines is to allow us to produce code written in a - consistent fashion, so that our product line will look similar throughout the line. The guiding - philosophy for choosing the described coding style is to avoid bugs when writing code, keep the code - maintainable, and also aim to make it beautiful. Some of the decisions are purely a matter of taste, - but have been made to keep the code consistent overall (say, camelCasing versus underscore_usage in - variable names.
- -
There are also many areas which are not covered by this document and there is some room to bring - your own style into the soup. Some of the ways of writing code are just purely matters of opinion. - The use of whitespace in code is a good example.
- -
This document is *not* the law of drawElements. If there is a good reason to deviate from it, you - should do that. However, if the reason is purely a matter of taste, then please follow the rules set - in here. Also, we want to encourage discussion about these guidelines and contributing to them, in - case you disagree or know a way of doing something better. This is meant to be an evolving document - that follows us as we learn as a group.
- -
A lot of examples are included in this document to make things easily readable and unambiguous. - For more source material, feel free to browse the source code of whichever drawElements projects - you have visibility to. You should see at least debase and depool libraries, if nothing - else.
-
Languages of choice -
The main languages at drawElements are Ansi C89 and ISO C++ 98. Ansi C is used for developing - driver or middleware IP, while C++ can be used for stand-alone applications.
- -
The reason for using C for middleware IP development is that we build software for - mobile devices and the compilers there are often of dubious quality, especially when it comes to - support of C++. In addition C++ runtime library is a non-trivial dependency.
- -
Stand-alone userspace applications can be written in ISO C++11.
- -
For utility and tool development, other languages may also be used. So far, Python has been used - for all such development and is encouraged to be used in future tools as well. If there are strong - reasons, other languages may also be considered.
-

C code example - -

Let's get started with some sample drawElements code. The code files below show a simple random - "class" implemented in C89. The code is taken from the drawElements base portability library, debase.

deRandom.h: The header file.

-#ifndef _DERANDOM_H
-#define _DERANDOM_H
-/*-------------------------------------------------------------------------
- * drawElements Base Portability Library
- * -------------------------------------
- *
- * Copyright 2014 The Android Open Source Project
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- *
- * Id: $Id$
- *//*!
- * \file
- * \brief Random number generation.
- *//*--------------------------------------------------------------------*/
-
-#ifndef _DEDEFS_H
-#   include "deDefs.h"
-#endif
-
-DE_BEGIN_EXTERN_C
-
-/*--------------------------------------------------------------------*//*!
- * \brief Random number generator.
- *
- * Uses the Xorshift algorithm for producing pseudo-random numbers. The
- * values are generated based on an initial seed and the same seed always
- * produces the same sequence of numbers.
- *
- * See: http://en.wikipedia.org/wiki/Xorshift
- *//*--------------------------------------------------------------------*/
-typedef struct deRandom_s
-{
-    deUint32	x;      /*!< Current random state.  */
-    deUint32	y;
-    deUint32	z;
-    deUint32	w;
-} deRandom;
-
-void        deRandom_init           (deRandom* rnd, deUint32 seed);
-deUint32    deRandom_getUint32      (deRandom* rnd);
-float       deRandom_getFloat       (deRandom* rnd);
-deBool      deRandom_getBool        (deRandom* rnd);
-
-DE_END_EXTERN_C
-
-#endif /* _DERANDOM_H */
-

deRandom.c: The implementation file.

-/*-------------------------------------------------------------------------
- * drawElements Base Portability Library
- * -------------------------------------
- *
- * Copyright 2014 The Android Open Source Project
- * \todo insert legalese here.
- *
- * Id: $Id$
- *//*!
- * \file
- * \brief Random number generation.
- *//*--------------------------------------------------------------------*/
-
-#include "deRandom.h"
-
-#include 
-#include 
-
-DE_BEGIN_EXTERN_C
-
-/*--------------------------------------------------------------------*//*!
- * \brief Initialize a random number generator with a given seed.
- * \param rnd	RNG to initialize.
- * \param seed	Seed value used for random values.
- *//*--------------------------------------------------------------------*/
-void deRandom_init (deRandom* rnd, deUint32 seed)
-{
-    rnd->x = (deUint32)(-(int)seed ^ 123456789);
-    rnd->y = (deUint32)(362436069 * seed);
-    rnd->z = (deUint32)(521288629 ^ (seed >> 7));
-    rnd->w = (deUint32)(88675123 ^ (seed << 3));
-}
-
-/*--------------------------------------------------------------------*//*!
- * \brief Get a pseudo random uint32.
- * \param rnd	Pointer to RNG.
- * \return Random uint32 number.
- *//*--------------------------------------------------------------------*/
-deUint32 deRandom_getUint32 (deRandom* rnd)
-{
-    const deUint32  w = rnd->w;
-    deUint32        t;
-
-    t = rnd->x ^ (rnd->x << 11);
-    rnd->x = rnd->y;
-    rnd->y = rnd->z;
-    rnd->z = w;
-    rnd->w = w = (w ^ (w >> 19)) ^ (t ^ (t >> 8));
-    return w;
-}
-
-/*--------------------------------------------------------------------*//*!
- * \brief Get a pseudo random float in range [0, 1[.
- * \param rnd	Pointer to RNG.
- * \return Random float number.
- *//*--------------------------------------------------------------------*/
-float deRandom_getFloat (deRandom* rnd)
-{
-    return (deRandom_getUint32(rnd) & 0xFFFFFFFu) / (float)(0xFFFFFFFu+1);
-}
-
-/*--------------------------------------------------------------------*//*!
- * \brief Get a pseudo random boolean value (DE_FALSE or DE_TRUE).
- * \param rnd	Pointer to RNG.
- * \return Random float number.
- *//*--------------------------------------------------------------------*/
-deBool deRandom_getBool (deRandom* rnd)
-{
-    deUint32 val = deRandom_getUint32(rnd);
-    return ((val & 0xFFFFFF) < 0x800000);
-}
-
-DE_END_EXTERN_C
-

C++ code example - -

The following code, taken from deutil demonstrates how C++ classes should look like.

deUniquePtr.hpp: Unique pointer template.

-#ifndef _DEUNIQUEPTR_HPP
-#define _DEUNIQUEPTR_HPP
-/*-------------------------------------------------------------------------
- * drawElements C++ Base Library
- * -----------------------------
- *
- * Copyright 2014 The Android Open Source Project
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- *
- *//*!
- * \file
- * \brief Unique pointer.
- *//*--------------------------------------------------------------------*/
-
-#ifndef _DEDEFS_HPP
-#   include "deDefs.hpp"
-#endif
-
-namespace de
-{
-
-/*--------------------------------------------------------------------*//*!
- * \brief Unique pointer
- *
- * UniquePtr is smart pointer that retains sole ownership of a pointer
- * and destroys it when UniquePtr is destroyed (for example when UniquePtr
- * goes out of scope).
- *
- * UniquePtr is not copyable or assignable. Pointer ownership cannot be
- * transferred between UniquePtr's.
- *//*--------------------------------------------------------------------*/
-template<typename T, class Deleter = DefaultDeleter<T> >
-class UniquePtr
-{
-public:
-    explicit    UniquePtr       (T* const ptr, Deleter deleter = Deleter());
-                ~UniquePtr      (void);
-
-    T*          get             (void) const throw() { return m_ptr;    }   //!< Get stored pointer.
-    T*          operator->      (void) const throw() { return m_ptr;    }   //!< Get stored pointer.
-    T&          operator*       (void) const throw() { return *m_ptr;   }   //!< De-reference stored pointer.
-
-    operator    bool            (void) const throw() { return !!m_ptr;  }
-
-private:
-                UniquePtr       (const UniquePtr<T>& other); // Not allowed!
-    UniquePtr   operator=       (const UniquePtr<T>& other); // Not allowed!
-
-    T* const    m_ptr;
-    Deleter     m_deleter;
-};
-
-/*--------------------------------------------------------------------*//*!
- * \brief Construct unique pointer.
- * \param ptr Pointer to be managed.
- *
- * Pointer ownership is transferred to the UniquePtr.
- *//*--------------------------------------------------------------------*/
-template<typename T, class Deleter>
-inline UniquePtr<T, Deleter>::UniquePtr (T* const ptr, Deleter deleter)
-    : m_ptr     (ptr)
-    , m_deleter (deleter)
-{
-}
-
-template<typename T, class Deleter>
-inline UniquePtr<T, Deleter>::~UniquePtr (void)
-{
-    m_deleter(m_ptr);
-}
-
-} // de
-
-#endif // _DEUNIQUEPTR_HPP
-

Naming conventions and formatting -
1. Basic naming conventions -
  Each project should have a prefix of its own. For drawElements base libraries, - the prefix de is used. Other projects should use a different, arbitrary prefix. - For instance, the stitcher project uses the xo prefix.
  - -
  Anything which has a reasonable possibility of causing a naming conflict should be - prefixed. This includes files, structs, enums, functions (except private ones), macros, etc. - In C projects, just about everything in the code needs to be prefixed (files, struct, enums, - global functions, etc.), but in C++ code, namespaces remove the need for most prefixing. - File names and macros should still be prefixed in C++ code as well. Note that members - of classes (either C or C++), or structs or unions do not need to be prefixed with the - package prefix.
  - -
  Identifiers are generally typed in camelCase. This applies to file names, structs, - enums, local variables, and struct members. In some cases, prefixes are used to clarify - the behavior of a variable. Static variables are prefixed with s_, global variables - with g_, and C++ class member variables with m_. Macros and enum entries should - always be written in UPPER_CASE with underscores separating the words. Members of C classes - don't need to be prefixed.
  - -
  When emulating classes in C, the class name itself should be written in CamelCase, but - starting with a upper-case letter. Usually the classes are prefixed: xoArmEmu, - deRandom, but if the class only exists within a single .c file, the prefix can be - omitted: StringBuilder. The member functions of the class should be prefixed with - the full class name and an underscore, followed by a camelCased function name: - xoArmEmu_emulateCode().
  - -
  Examples of correctly named identifiers:
  -
  - dePool.c, dePool.h, deUniquePtr.hpp, deThread.cpp -- file names
  - deRandom, xoStitcher -- structs / classes
  - deMemPoolFlag, xoConditionCode -- enums
  - DE_COMPILER_MSC -- macros
  - XO_BACKEND_NEON -- enum entry
  - setTableSize() -- local (static) function
  - xoArmEmu_emulateCode() -- C class member function
  - numVariables -- local variable
  - m_itemHash -- member variable in a C++ class
  - s_rcpTable -- static variable in a function
  - g_debugFlag -- global variable
  -
2. Choosing good names -
  Naming your variables is somewhat of a black art, but the main goal of giving a name should - be clarity. You want to communicate what the contents of the variable mean. The more obscure - the purpose of a variable is, the longer (and more descriptive) a name you should invent for it. - Also, the longer the life time of a variable is, the longer a name it deserves. For example, a - loop counter which is alive for page worth of code should be named something like vertexNdx, - whereas a loop counter which lives only a couple of lines can be named simply i or ndx.
  - -
  Most variables should be declared const and never changed (see coding philosophy section). - Thus one often successful approach for variable naming is to give name for the value instead. - For example when querying first child of node and storing it in variable, that should be named - as firstChild instead of node.
  - -
  Consistency is one important factor in naming variables. When a similar kind of name is needed - in multiple places, choose a way of devising the name and stick to that. E.g., if you query the - number of elements in an array to a local variable in several functions, always use the same name - in each of the functions.
  - -
  When dealing with counts or numbers (number of elements in an array, etc.), you should always - clearly indicate with the name that this is the case, e.g., numElements (preferred), - elementCount, etc. Which ever prefix or postfix you choose to use, stick to it.
  - -
  Function parameters that have an unit of measure (e.g. seconds or bytes) should have the unit - as part of the name, for example timeLimitMs and chunkSizeKb.
  - -
  Use American English instead of English English. Choose gray over grey, color over colour, - and so forth.
  -
3. Canonical abbreviations - - - - - - -
  buffer buf
  destination dst
  index ndx
  source src
  variable var
  -
4. Struct and enum typedeffing -
  For enums and structs, the types should always be typedeffed and used without the struct or - enum prefix in actual code.
  - -
  Example.
  -
```
-/* Declaration. */
-typedef enum xoConditionCode_e
-{
-    ...
-} xoConditionCode;
-
-typedef struct deMempool_s
-{
-    ...
-} deMemPool;
-
-/* Usage. */
-deMemPool*        memPool;
-xoConditionCode   condCode;
-
```
  -
5. Header files and including -
  All header files should have include guards in them to avoid processing them multiple times - in case they are included from multiple places. The style used for the macro is _FILENAME_H, - for example: _DEDEFS_H. Whenever including other headers from a header file, you should - always use external include guards as well. The external include guards considerably reduce the - number of file accesses that the compiler needs to make, resulting in faster compile times.
  - -
  Each implementation file should have matching header file and vice versa. The implementation - file must include the corresponding header file first. By doing that, it is guaranteed that the - header file includes all of its dependencies.
  - -
  Each header file should first include deDefs.h, or alternatively project-specific - xxDefs.h/hpp file that in turn includes deDefs.h. That way all the usual types and macros - are always properly defined.
  - -
  External include guard example.
  -
```
-#ifndef _DEDEFS_H
-#   include "deDefs.h"
-#endif
-#ifndef _DEINT32_H
-#   include "deInt32.h"
-#endif
-#ifndef _DEUNIQUEPTR_HPP
-#   include "deUniquePtr.hpp"
-#endif
-
```
  - -
  The include order of files should start from debase (esp. deDefs.h), go thru - other base libraries, then your own project header files, and lastly the system header files. - Also, a .c file must include its own header file first. E.g., deMemPool.c must - first include deMemPool.h.
  - -
  Every include path must also end up including deDefs.h before any actual code is processed. - This ensures that the basic portability macros (DE_OS, DE_COMPILE, etc.) have been - defined.
  -
6. Indenting and whitespace -
  Code should be indented with tabs (instead of spaces) and a tab-width of 4 characters should - be used.
  - -
  Always put braces on their own lines. This applies to functions, structs, enums, ifs, loops, - everything. The only exception are single-line scopes. For one-statement ifs or loops, braces - should not be used. Also, put else and else if on their own lines as well.
  - -
  Brace usage
  -
```
-void main (int argc, const char** argv)
-{
-    if (argc > 1)
-        parseArgs(argv[1]);
-    else
-    {
-        printf("Usage:\n");
-        printf("...\n");
-    }
-}
-
```
  - -
  In addition to only indenting your code, things like variable names in a list of - declarations or comments at the end of line, should also be aligned such that they start at - the same column. Compare the following two examples of the same code, only with differing - alignments in the text.
  - -
  Aligned variable declarations and comments.
  -
```
-struct deMemPool_s
-{
-    deUint32        flags;         /*!< Flags.                                      */
-    deMemPool*      parent;        /*!< Pointer to parent (null for root pools).    */
-    deMemPoolUtil*  util;          /*!< Utilities (callbacks etc.).                 */
-    int             numChildren;   /*!< Number of child pools.                      */
-    deMemPool*      firstChild;    /*!< Pointer to first child pool in linked list. */
-    deMemPool*      prevPool;      /*!< Previous pool in parent's linked list.      */
-    deMemPool*      nextPool;      /*!< Next pool in parent's linked list.          */
-    ...
-};
-
```
  - -
  No alignments used.
  -
```
-struct deMemPool_s
-{
-    deUint32 flags; /*!< Flags. */
-    deMemPool* parent; /*!< Pointer to parent (null for root pools). */
-    deMemPoolUtil* util; /*!< Utilities (callbacks etc.). */
-    int numChildren; /*!< Number of child pools. */
-    deMemPool* firstChild; /*!< Pointer to first child pool in linked list. */
-    deMemPool* prevPool; /*!< Previous pool in parent's linked list. */
-    deMemPool* nextPool; /*!< Next pool in parent's linked list. */
-    ...
-};
-
```
  -
7. Other formatting - -
  Always use C-style comments in C code: /* This is a C comment. */ Only use - the C++ // end-of-line comments in C++ code.
  - -
  Comment styles.
  -
```
-/* Use this kind of comments in C code. */
-
-// This kind of comments may only be used in C++ code.
-
```
  - -
  Pointer and references.
  -
```
-// Good: pointers and references are a part of the type
-void*          ptr;
-deInt32*       colorBuffer;
-xoArmEmu*      armEmu;
-Array<int>&    intArray;
-void doBlend (deUint32* dst, const deUint32* src);
-
-// Bad: pointer symbol should not be a part of the name
-void *ptr;
-void doBlend (deUint32 *dst, const deUint32 * src);
-
```
  - -
  Formatting of function declarations.
  -
```
-// Good: void if empty param list, empty space after name, braces on own line
-void doStuff (void)
-{
-}
-
-// Bad: horrible function name!
-void doStuff() {
-}
-
-// Good: separate arguments with spaces, function name
-ShapeList getIntersectingShapes (float x, float y, float z)
-{
-}
-
-// Bad: function name (list of what volumes?), no space after commas in arg list
-ShapeList getShapeList (float x,float y,float z)
-{
-}
-
-// Exception: sometimes simple function are best written as one-liners
-float deFloatAbs (float f) { return (f < 0.0f) ? -f : f; }
-
-
```
  - -
  Formatting of control statements.
  -
```
-// Good: no extra braces for one-liner if cases
-if (a.isZero)
-    result = 0.0f;
-else
-    result = a.value * (1.0 / 65536.0f);
-
-// Bad: extraneous braces, bad whitespace usage
-if (a.isZero)
-{
-    result=0.0f;
-}
-else
-{
-    result=a.value*(1.0 / 65536.0f);
-}
-
-// Good: expression easy to read
-if (a.isZero && b.isZero)
-{
-    ...
-}
-
-// Bad: missing spaces around && operator, missing space after 'if'
-if(a.isZero&&b.isZero)
-{
-    ...
-}
-
-// Good: else on its own line
-if (alpha == 0)
-{
-    ...
-}
-else if (alpha == 255)
-{
-    ...
-}
-else
-{
-    ...
-}
-
-// Bad: else on same line as closing brace
-if (alpha == 0)
-{
-    ...
-} else if (...)
-{
-    ...
-} else
-{
-    ...
-}
-
-// Good: note space after 'while'
-while (numTriangles--)
-{
-    ...
-}
-
-// Bad: whitespace usage
-while(numTriangles --)
-{
-    ...
-}
-
-// Good: while on same line as closing brace
-do
-{
-    ...
-} while (--numTriangles);
-
-// Bad: while on its own line, missing whitespace after 'while'
-do
-{
-    ...
-}
-while(--numTriangles);
-
-// Good: easy to read
-for (ndx = 0; ndx < numTriangles; ndx++)
-
-// Bad: missing spaces all over (whitespace should be used to separate expressions)
-for(ndx=0;ndx<numTriangles;ndx ++)
-
-// Good: note missing braces for while, correct usage of whitespace
-while (numTriangles--)
-    area += computeArea(triangle[ndx++]);
-
-// Bad: don't put unnecessary braces, avoid extraneous whitespace in expressions
-while (numTriangles--)
-{
-    area+=computeArea( triangle [ndx++] );
-}
-
```
  - -
  Formatting switch cases.
  -
```
-// Good: case-statements indented, code indented another level (including breaks)
-switch (blendMode)
-{
-    case XX_BLENDMODE_NORMAL: // no variable declarations
-        ...
-        break;
-
-    case XX_BLENDMODE_SRC_OVER: // need braces if declaring variables inside
-    {
-        int alpha = ...;
-        break;
-    }
-
-    case XX_BLENDMODE_XYZ:
-        ...
-        // FALLTHRU! -- make non-breaked cases very explicit!
-
-    default: // handles the final blendmode (DISABLED) with an assertion!
-        DE_ASSERT(blendMode == XX_BLENDMODE_DISABLED);
-
-        break; // always put break!
-}
-
-// Bad:
-switch(blendMode)
-{
-case XX_BLENDMODE_NORMAL: // always indent case labels
-    ...
-break; // put break on same level as indented code!
-
-case XX_BLENDMODE_SRC_OVER:
-    {
-        ...
-        break;
-    }
-
-case XX_BLENDMODE_XYZ:
-    ...
-
-case XX_BLENDMODE_DISABLED: // always comment the case fall-through (like above)
-    ...
-} // default case missing! always need to handle it (and assert if illegal!)
-
```
  - -
  Formatting of expressions.
  -
```
-// Good: parenthesis or whitespace used to indicate evaluation order
-array[(a * b) + c];
-array[a*b + c];
-
-// Bad: order unclear
-array[a*b+c];
-
-// Good: parenthesis (or whitespace) makes evaluation order unambiguous
-array[(a && b) || (c == 0)]
-array[a==0 || b==0 || c==0] // in some cases spaces can be used instead of parenthesis
-
-// Bad: unclear evaluation order
-array[a&&b || c==0] // does this even work?
-array[a == 0 || b == 0 || c == 0]
-
-// Good: easy to see different parts of evaluation (whitespace where it matters)
-array[triangle->index0 - cache.baseIndex];
-
-// Bad: hard to read (whitespace around brackets doesn't help readability!)
-array[ triangle->index0-cache.baseIndex ];
-array [triangle -> index0 - cache.baseIndex];
-
-// Good: easy to see all function arguments
-computeArea(vtx0.x, vtx0.y, vtx1.x, vtx1.y, vtx2.x, vtx2.y);
-
-// Bad: missing spaces makes it hard to read, no space after function name when calling
-computeArea ( vtx0.x,vtx0.y,vtx1.x,vtx1.y,vtx2.x,vtx2.y );
-
-// Good: readable (the code itself is a made-up example and thus incomprehensible)
-// Consider: would probably make more readable code to use temporary variables here
-if (sizeArray[a+5] > getSize(getFoo()+2))
-if (sizeArray[a + 5] > getSize(getFoo() + 2))
-
-// Bad: whitespace usage confuses rather than helps
-if(sizeArray[a+5]>getSize(getFoo()+2))
-if ( sizeArray [ a + 5 ] > getSize ( getFoo () + 2 ) )
-
-// Bad: unclear (and wrong) evaluation order
-if (bitMask & (1<<bit) == 0)
-
```
  - -
  Other formatting.
  -
```
-#if defined(DE_DEBUG)      // prefer #if defined() to #ifdef
-    ...
-#endif /* DE_DEBUG */      // only put ending comment if #if is far away
-
-
```
  -
-

Base library services -

TODO: explain all of these

- -

debase/deDefs.h -

-- DE_COMPILER, DE_OS, DE_CPU
-- basic types (deUint8, deIntptr, deBool==int, ..)
-- DE_NULL
-- DE_DEBUG -- #if defined(DE_DEBUG)
-- DE_INLINE
-- DE_ASSERT(), DE_VERIFY(), DE_TEST_ASSERT(), DE_STATIC_ASSERT()
-- DE_BREAKPOINT()
-- DE_SWAP()
-- DE_LENGTH_OF_ARRAY()
-- DE_OFFSET_OF()
-- DE_UNREF()
-- DE_BEGIN_EXTERN_C, DE_END_EXTERN_C
-- DE_NULL_STATEMENT

Other debase headers -

-- deInt32.h: deInRange32(), deInBounds32(), hashing
-- deFloat16.h: fp16<->fp32
-- deMath.h: generic float math
-- deRandom.h: random number generation
-- deMemory.h: allocating memory, deMemset(), deMemcpy(), DE_NEW(), DE_DELETE()
-- deString.h:

depool services -

-- memory pools (deMemPool)
-- pooled data structures
-  * Array
-  * Set
-  * Hash
-  * HashArray
-  * HashSet

Commenting code -

File comment boxes -

Each source file should contain the following comment box. In header files the comment is placed after - the #ifdef-#endif pair. On implementation files the comment box is placed at the beginning.

-/*-------------------------------------------------------------------------
- * Full Module Name
- * ----------------
- *
- * Copyright 2014 The Android Open Source Project
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- *
- *//*!
- * \file
- * \brief Short description of the contents.
- *
- * Followed by longer description if necessary (such as high-level algorithm
- * description).
- *//*--------------------------------------------------------------------*/
--

Structs/classes/enums comment boxes -
TODO:
-
Other Doxygen comment boxes (/** ... */ and /*!< ... */) -
TODO: single-line, multi-line
-

Code comments -

Below and example of code commenting for C. When doing C++, you can replace C-style comments with C++-comments.

-callFoo(&a);
-
-/* Comment about following block (Note empty line before and after)*/
-
-callBar(&b);
-c = a + b; /* Why we need to do this op */
-doItAll(a, b, c);
-
-/* Badness starts with this comment */
-callBar(&b);
-/* Why we need to do this op */
-c = a + b;
-doItAll(a, b, c);
-
-

Tags -
Todo-comments should use the following syntax:
-
```
-/* \todo [2012-01-26 pyry] Give a longer description of todo-usage in code. */
-
```
-
If you wish to communicate to fellow developer about some unexpected behavior or corner-case - that is not obvious, \note tag can be used.
-
```
-/* \note Tangent may be zero. */
-
```
-

Generic programming -
1. Classes in C -
  TODO: explain
  -
2. Const correctness -
  When declaring function arguments, local variables, or class members, all non-mutable ones - must be declared const. Declaring variable const communicates clearly your intent to not modify - the given value. This is especially important in function argument lists.
  - -
  Declaring local variables, or function arguments that are passed by value, const, may be a bit - controversial. There are indeed a lots of existing code that doesn't follow this rule. However, - adding extra constness has proven to improve code readability a quite bit and thus all new code - must use const correctly. The only exception is function arguments passed by value; for those - const keyword can be omitted. By-value function arguments are however considered to be const - for all purposes.
  - -
  Example.
  -
```
-// Function example. Note const qualifier on maxDepth as well which is passed by value.
-static glu::VarType generateRandomType (const int maxDepth, int& curStructIdx, vector<const StructType*>& structTypesDst, Random& rnd)
-{
-    const bool isStruct     = maxDepth > 0 && rnd.getFloat() < 0.2f;
-    const bool isArray      = rnd.getFloat() < 0.3f;
-
-    ...
-}
-
-// Class members
-class Node
-{
-public:
-                   Node      (Node* const parent);
-                   ~Node     (void);
-
-    ...
-private:
-    Node* const    m_parent;
-};
-
-Node::Node (Node* const parent)
-    : m_parent(parent) // Const members can be initialized
-{
-}
-
```
  -
3. Declaring variables -
  All variables should be declared at the beginning of a block. If variables are introduced in - the middle of code, nested block must be used. This is what ANSI C requires, and the same style must - be used in C++ code as well. The only exception for this is loop counters in C++; they may be - declared in loop init expression.
  - -
  Having variable declarations always at the beginning of the block makes code easier to read - as no new state is introduced in the middle of code. It also guides towards writing smaller - functions that don't use too many variables.
  - -
  Example.
  -
```
-static void logTransformFeedbackVaryings (TestLog& log, const glw::Functions& gl, const deUint32 program)
-{
-    int numTfVaryngs    = 0;
-    int	maxNameLen      = 0;
-
-    gl.getProgramiv(program, GL_TRANSFORM_FEEDBACK_VARYINGS, &numTfVaryngs);
-    gl.getProgramiv(program, GL_TRANSFORM_FEEDBACK_VARYING_MAX_LENGTH, &maxNameLen);
-    GLU_EXPECT_NO_ERROR(gl.getError(), "Query TF varyings");
-
-    {
-        vector<char> nameBuf(maxNameLen+1);
-
-        for (int ndx = 0; ndx < numTfVaryngs; ndx++)
-        {
-            ...
-
```
  -
4. Variable life-time -
  TODO: minimize life-time of a variable (may sometimes need additional scopes in C)
  -
5. Enumerations -
  TODO: assign zero to first, let compiler assign others (in typical lists)
  -
  TODO: use ENUM_LAST
  -
  TODO: mask values
  -
  TODO: use instead of #defines
  -
  TODO: typedef xxEnumName_e trick (already explained above?)
  -
6. Error handling -
  There are generally two types of errors that can occur in code; errors that stem from environment - or bad input, and errors that are caused by logic error in the code. Former ones are typically - outside our control (such as running into a network error) and latter are simply programming mistakes.
  - -
  External errors must be handled in a graceful way. Depending on the project it may include handling - out-of-memory situations as well (most certainly when doing drivers or middleware). In C function return - value should be used for communicating whether external error was hit. In C++ code exceptions can - be used as well. Assertions must not be used for checking external error conditions.
  - -
  Internal logic errors must be checked with assertions. See next section.
  -
7. Assertions -
  Assertions are a form of code documentation. They explicitly declare what the code expects from - input values or current state. They are tremendously useful when trying to understand how certain - piece of code should be used. In addition they are a very nice debugging aid as they help catch logic - errors early on before those errors get chance to corrupt program state.
  - -
  Functions should assert all non-trivial input data and conditions. The one notorious exception is - that pointer validity doesn't need to be asserted if the pointer is dereferenced immediately. - Non-trivial computation results should also be checked with assertions.
  - -
  Example.
  -
```
-// Examples of good assertions:
-void* deMemPool_alignedAlloc (deMemPool* pool, int numBytes, deUint32 alignBytes)
-{
-    void* ptr;
-    DE_ASSERT(pool); // Must be asserted since not dereferenced but passed to another function
-    DE_ASSERT(numBytes > 0); // Assertion on input data condition
-    DE_ASSERT(deIsPowerOfTwo32((int)alignBytes)); // Non-trivial input condition
-    ptr = deMemPool_allocInternal(pool, numBytes, alignBytes);
-    DE_ASSERT(deIsAlignedPtr(ptr, alignBytes)); // Assertion on computation result
-    return ptr;
-}
-
-// Badness starts here
-
-void getTextureWidth (const Texture* texture)
-{
-    DE_ASSERT(texture); // Bad: unnecessary, will crash anyway if texture is null
-    return texture->width;
-}
-
-void doStuff (void)
-{
-    int i = 3;
-    i += 2;
-    DE_ASSERT(i == 5); // Bad: assertion on trivial computation result
-
-    FILE* f = fopen("myfile.txt", "rb");
-    DE_ASSERT(f); // Bad: there are legitimate reasons for failure
-}
-
```
  - -
8. Lookup tables -
  TODO: DE_STATIC_ASSERT lookup table size - should usually match to ENUM_TYPE_LAST
  - -
```
-typedef enum xxBlendEquation_e
-{
-    XX_BLEND_EQUATION_ADD = 0,
-    XX_BLEND_EQUATION_SUBTRACT,
-    XX_BLEND_EQUATION_REVERSE_SUBTRACT,
-
-    XX_BLEND_EQUATION_LAST
-} xxBlendEquation;
-
-// Note: size is left for compiler to figure out
-static const s_blendModeMap[] =
-{
-    GL_FUNC_ADD,                // XX_BLEND_EQUATION_ADD
-    GL_FUNC_SUBTRACT,           // XX_BLEND_EQUATION_SUBTRACT
-    GL_FUNC_REVERSE_SUBTRACT    // XX_BLEND_EQUATION_REVERSE_SUBTRACT
-};
-// This will cause compilation failure lookup table size gets out of date
-DE_STATIC_ASSERT(DE_LENGTH_OF_ARRAY(s_blendModeMap) == XX_BLEND_EQUATION_LAST);
-
```
  -
9. Struct size -
  TODO: DE_STATIC_ASSERT of struct sizes
  -
  TODO: use small datatypes (deUint8 instead of deBool) when size matters.
  -
10. Extraneous code -
  TODO: avoid too verbose code.
  - -
  Example.
  -
```
-// Good: compact without sacrificing readability
-return (a < 0.0f) ? -a : a;
-
-// Bad: waste of space
-float result;
-if (a < 0.0f)
-{
-    result = -a;
-}
-else
-{
-    result = a;
-}
-return result;
-
```
  - -
-
C++ topics -
1. Class declarations -
  TODO: how declaration looks like (already shown in example..)
  -
  TODO: function definitions inside class ok if single-line, other special cases
  -
2. Class boilerplate -
  TODO: copy ctor, assignment operator
  -
3. Code Formatting -
```
-
-// Constructors
-FooAtom::FooAtom(int proton, float electron)
-	: m_proton    (proton)   // Note aligning member initializers.
-	, m_electron  (electron)
-{
-
-}
-
-// Remember to add the name of the namespace at the end of the namespace
-namespace foo
-{
-
-// Namespaces aren't indented
-class Proton;
-
-...
-} // foo
-
```
  -
4. RAII -
  Everyone should get familiar with RAII. In a nutshell, "resource acquisition is initialization" - means that a class destructor must always release all resources (such as memory or OS handles) - that have been allocated during the whole lifetime of the object.
  - -
  RAII is essential for exception-safe code. You should always make sure that if an exception is - thrown, including out-of-memory cases, your code behaves properly and releases all allocated resources.
  -
5. Pointers and references -
  In C++ references should be generally preferred over pointers. The main difference between pointers - and references is that references can not change, and are not expected to be null. References should be - used instead of pointers for passing objects when both conditions hold; object can not be null nor - reference won't be modified once initialized.
  -
  Pointers are used when there is need to change the address, or it can be null for a valid reason. - Additionally, pointers are always used for passing basic type or object arrays.
  -
6. Containers -
  TODO: describe stl container usage policies
  -
7. Exceptions -
  TODO: exceptions can be used, custom ones must be based on std::exception
  -
8. Polymorphism -
  TODO: when to use virtual functions, virtual destructor
  -
9. Namespaces -
  TODO: namespace naming
  -
  TODO: using statement, never using in headers
  -
-
Tools -
1. Git -
  Git is currently the weapon of choice for source control management. Even though it is - not the perfect solution, it gets job done well, or at least better than most other solutions.
  - -
  Our repositories are hosted on github.com. You are allowed and encouraged to push any number - of new branches to the github repositories. Remember to clean up the obsolete ones after they - have been merged to master. But never delete a remote branch that hasn't been created by you.
  - -
  Before you commit anything, make sure user.name and user.email are properly set up.
  -
```
-git config --global user.name "Veijo Elements"
-git config --global user.email "veijo.elements@drawelements.com"
-
```
  - -
  The standard line ending format for all text files is Unix-style. The best way to handle - line endings on Windows systems is to set core.autocrlf to input. That causes - conversion to Unix-style line endings on commit only (i.e. not in checkout).
  -
```
-git config --global core.autocrlf input
-
```
  - -
  In order to keep trailing whitespace out of source tree, a standard pre-commit hook must - be placed in each local clone of any source repositories.
  -
```
-# in repository directory
-cp ~/Dropbox/drawElements/Misc/git/pre-commit .git/hooks/
-
```
  -
2. Build systems and IDEs -
  CMake is used as an official project file generator. CMake can be used to generate makefiles - or project files for most IDEs. Unless there is a good reason, you should use project files - generated by CMake.
  - -
  You are free to choose any IDE or editor you like. At least Visual Studio, vim and - emacs have been successfully used in the past. Good debugger integration is strongly recommended.
  -
-
Coding philosophy -
1. Designing classes -
  Each class should have only a single purpose to fulfill, and it should encapsulate that - entirely. All functionality that is secondary and doesn't require access to classes' internal - implementation should not be part of that class. This is called - single responsibility principle. It is probably easier to grasp it with an example.
  - -
  Consider a Texture2D class that manages 2D-dimensional texture data. Such class is clearly - responsible for managing lifetime of the associated memory, and storing properties such as - size and format. Now, one could need a function for blitting (copying) portion of one texture - to some position in an another texture. This could be added as a method to texture class, but - it most certainly isn't core responsibility of that class. So correct way to implement that - is either as a plain function operating on publicly accessible methods of Texture2D class, - or as a separate Blitter class. Same applies to things such as reading texture from a file, - clearing the texture to a certain color and so forth.
  - -
  Texture class example.
  -
```
-class Texture2D
-{
-public:
-                        Texture2D       (const TextureFormat format, const int width, const int height);
-                        Texture2D       (const char* const filename); // Bad: not core functionality
-                        ~Texture2D      (void);
-
-    // Good methods: essential functionality
-    Vec4                getPixel        (const int x, const int y) const;
-    void                setPixel        (const int x, const int y, const Vec4& c);
-    const deUint8*      getPixelPtr     (void) const;
-
-    // Bad: non-essential
-    void                clear           (const Vec4& c);
-    bool                containsColor   (const Vec4& c) const;
-    void                setInitialized  (void); // Why texture would store bit that belongs outside?
-
-private:
-    // Good: essential, minimum data set
-    vector<deUint8>     m_pixels;
-    TextureFormat       m_format;
-    int                 m_width;
-    int                 m_height;
-
-//  deUint8*            m_pixels; // Bad: explicit mem. mgmt, not core functionality
-    bool                m_initialized; // Bad: extraneous information
-};
-
-// Good: independent functions operating on textures
-void        clearTexture    (Texture2D& texture, const Vec4& color);
-Texture2D*  createFromFile  (const char* const filename);
-
```
  -
  One sign of a successful class design is that the interface feels natural to use. Thus when - designing a new class from a scratch, you should start by writing the use cases first. Class - interface can be refined until it suits the most important use cases, and only then the - implementation is filled in. Doing things in reverse order often leads to interfaces that are - later found to be inadequate.
  - -
  When writing the internal implementation a lot of thought should be put on maintaining - consistent state, or more formally, class invariant. - Member variables in a class are a form of global state and thus special care must be taken - when manipulating that state. If class requires a lot of state, it can be helpful to group - some of the members into separate state-only classes whose sole responsibility is maintaining - the class invariant for that set of members. Another good pattern is to write a state validation - function that is called in debug builds after each non-trivial state change.
  - -
  Only a minimal set of class member variables should ever be used. If some value can be derived - with a relatively little effort from the minimal set of members, it must not be stored as a - member variable. In the Texture2D class example, length of a pixel row or image size can - be derived from size and format and thus member variables must not be used for them. - - - -
2. Global state -
  Pretty much everyone can agree that relying on global state is undesirable. However, what - is not always obvious is what counts as a global state. Global variables are clearly such state, - but many more can be considered as well. For example state encapsulated in shared objects, state - retained in library API, or even state passed in member variables between member functions - could be counted as a form global state. Another way to define global state is that it is anything - that can be passed from one function to another without including it in function call arguments.
  - -
  All forms of global state should be used only when necessary. Excluding some very rare cases, - mutable global variables are never necessary. Singletons are really just a fancier version of - global variables. Instead of using for example singleton for application log object, it should be - passed in explicitly to all objects and functions that require logging.
  - - -
3. Variables vs. immutable values -
  Traditional imperative programming puts emphasis on variables. They are thought of being - limited resource, used for storing immediate computation results for brief periods of time. - In early C days it was even common to declare variable register in order to communicate - the compiler that it should place the variable into a register. Things have changed a lot since - then, and it is no longer necessary to limit use of variables for performance reasons.
  - -
  Functional languages declare variables immutable, i.e. they are not really varying - values, but instead named values. This often greatly improves code clarity and correctness, - as variables can not change unexpectedly. While imperative languages certainly need some amout - of mutability, the concept of immutable values certainly has advantages.
  - -
  As discussed in variable naming section, you often should name a single value, not some - storage slot for arbitrary set of values. In such case it makes a lot of sense to treat that - as immutable named value, not mutable varibale. In C and C++ that can be explicitly declared - with use of const qualifier.
  - -
  In general the amount of state that is considered mutable in any given context should be - minimized. Understanding code is a much more easier if number of things that can change is - small. This also guides code towards natural separation into smaller functions.
  - -
  Limiting number of mutable variables leads to a more functional programming style, where a - lot of computation done in initializer expressions at the beginning of a block. This is not - necessarily a bad thing as it requires separating any non-trivial computation into separate - functions. Most often we only need the result of such computation anyway, and how the - value itself is computed is not important for the problem at hand. - -
  Complex code example.
  -
```
-std::vector<Node*> topologicalSortFromRoot (Node* const root)
-{
-    // Returning containers is OK if called functions are local and compiler
-    // can easily do return value optimization.
-    const std::vector<Node*>    allNodes    = collectAllNodesFromRoot(root); // Reduce number of mutables by computing outside
-    std::map<Node*, int>        useCounts   = computeUseCounts(allNodes); // Uses allNodes value, mutable
-    std::vector<Node*>          liveSet;        // Mutable as well
-    std::vector<Node*>          sortedNodes;    // Used as return value - only appended to
-
-    // We have multiple mutables here. Invariant is that each node that has zero in useCount
-    // must be either in liveSet or sortedNodes, but not in both.
-
-    for (std::vector<Node*>::iterator nodeIter = allNodes.begin();
-         nodeIter != allNodes.end();
-         ++nodeIter)
-    {
-        // Note that nodeIter is not considered mutable here - instead it is iteration-specific
-        // immutable value.
-        if (useCounts[*nodeIter] == 0)
-            liveSet.push_back(*nodeIter); // liveSet is used as return value here
-    }
-
-    while (!liveSet.empty())
-    {
-        Node* const curNode = liveSet.back();
-        liveSet.pop_back();
-
-        sortedNodes.push_back(curNode);
-
-        ...
-    }
-
-    return sortedNodes;
-}
-
```
  -
4. Pure functions -
  Pure functions have two properties. Firstly, the result depends only on the input values and - always produces same output value given same set of input values. Secondly, the function does not - cause any observable side effects or changes to global state. For example sin(x) is pure - function as it always returns the same value for same argument value and does not cause any side effects.
  - -
  As much of the code as possible should be kept pure. Moving pure parts of logic and computation - into separate functions is recommended. Unit testing those pure functions is then much easier.
  - -
  Mutating objects passed in counts as a side effect. Instead pure functions must return a completely - new value. This may not always be feasible and some functions may need to be impure for performance - reasons. One way to work around that while remaining as pure as possible is to use separate output-only - argument for output value. Perhaps the most ubiquitous example of such function is memcpy().
  - -
  Examples
  -
```
-// Good: pure function (assuming that it doesn't touch global state)
-vector<int> findUniqueNumbers (const vector<int>& numbers);
-
-// Good: single output-only parameter
-void        findUniqueNumbers (vector<int>& dst, const vector<int>& numbers);
-
-// Bad: copying a lot of data for sake of pureness
-LargeStateObject setStateX (const LargeStateObject& state, const int value);
-
-// Bad: manipulates input for no reason
-void        removeDuplicates  (vector<string>& words);
-
-
```
  -
- - - -

- -

buffer	buf
destination	dst
index	ndx
source	src
variable	var