coding_guide.txt

   1 1. Coding Style
   2
   3         You should follow the style of the file you're editing. In general, we
   4         try to follow the rules below.
   5
   6         1) indent with tabs, and a tab is always 8 characters wide
   7         2) opening braces are on the same line as the if statement
   8         3) no braces in an if-body with just one statement
   9         4) if one of the branches of an if-else codition has braces, than the
  10            other branch should also have braces
  11         5) there is always an empty line between variable declarations and the code
  12
  13         static int
  14         my_function(void)
  15         {
  16                 int a = 0;
  17                 if (a)
  18                         b();
  19                 else
  20                         c();
  21                 if (a) {
  22                         b();
  23                         c();
  24                 } else {
  25                         d();
  26                 }
  27         }
  28
  29         6) lines should be less than 80 characters wide
  30         7) when breaking lines with functions calls, the parameters are aligned
  31            with the opening parenthesis
  32         8) when assigning a variable with the result of a function call, if the
  33            line would be longer we break it around the equal '=' sign if it makes sense
  34
  35         long_variable_name =
  36                 function_with_a_really_long_name(parameter1, parameter2,
  37                                                  parameter3, parameter4);
  38         x = function_with_a_really_long_name(parameter1, parameter2,
  39                                              parameter3, parameter4);
  40
  41 2. Function names
  42         1) all internal function names should start with '__tpl'
  43         2) externally exposed function names should start with 'tpl'
  44
  45 3. Input argument checking
  46         1) internal functions should TPL_ASSERT on non-null for all pointer type
  47            argumentxs
  48                 Exception:
  49                 - NULL is valid value
  50                 - function is a validity checking function
  51         2) internal functions should not check for non-null for pointer type
  52            arguments with conditional branching
  53                 Execption: function is a validity checking function
  54         3) externally exposed functions should check for non-null for all
  55            pointer type arguments with 'if' statement
  56                 Execption: NULL is valid value
  57         4) when externally exposed function is return due to error, TPL_ERR
  58            should be called with appropriate error message
  59
  60 4. Function calling
  61         1) before calling internal function, caller function *MUST* check for
  62            value validity before passing it to the callee
  63            (internal functions do not check for input validity)
  64
  65 5. Return value
  66         1) functions should return a value
  67                 Exception:
  68                 - failure is ignorable
  69                 - failure not possible
  70         2) default return values should be TPL_TRUE on success and TPL_FALSE on
  71            failure
  72         3) functions that return pointer value *MUST* return NULL on error
  73         4) other functions which return values useful to other callee may return
  74            that value
  75
  76 6. Documentation
  77         1) *ALL* functions in libtpl-egl *MUST* be documented in Doxygen format
  78         2) functions *MUST* have at least brief, param, and return sections
  79
  80 7. Enumeration type
  81         1) *ALL* enums *MUST* start with error code, 'xxx_ERROR' and assigned
  82            value of -1
  83         2) *ALL* enums *MUST* have identifier named 'xxx_MAX' to signify the end
  84            of the enum list (i.e. 'TPL_OBJECT_MAX')