CODING

   1 INTRODUCTION
   2 ---------------------------------------------------------------------
   3 Here will you find coding standards to the project. Requirements are
   4 listed in their respective files and can be considered an adendum to
   5 this document.
   6
   7
   8 CODING STYLE
   9 ---------------------------------------------------------------------
  10 See linux/Documentation/CodingStyle.
  11
  12 Some highlights:
  13
  14 - Outside of comments and documentation, never
  15   use spaces. Identation is done using tabs only.
  16
  17 - Do not use tabs to align text documentation. Changing tab
  18   width should not interfere with the layout/alignment of code,
  19   only indentation.
  20
  21 - functions are declared like this:
  22    char *function(const char *test)
  23    {
  24
  25    }
  26
  27 - if you use brackets INSIDE a function put them on the same line
  28
  29     Wrong:
  30     if (condition)
  31     {
  32         do_something;
  33     }
  34
  35     Right:
  36     if (condition) {
  37         do_something;
  38     }
  39
  40 - Do not put actions in the same line of conditions:
  41
  42     Wrong:
  43     if (condition) do_this;
  44
  45     Right:
  46     if (condition)
  47         do_this;
  48
  49 - Also it is a good practice to use always brackets in conditions:
  50
  51          if (condition) {
  52                 do_only_this;
  53          }
  54
  55 - Variables are always in lower case (like tmp_buf)
  56 - New defined types are capitalized (like OSyncEngine)
  57 - Never use typedefs just to hide pointers
  58
  59 - External APIs, used for integration between components may
  60   look like this:
  61
  62         osync_engine_init()
  63
  64 - Always add the osync_ prefix to your functions
  65
  66 - Do not return function calls, like "return do_something();",
  67   instead, use a auxiliar variable (rationale: easy trace).
  68
  69 - When doing error checking, use goto to help creating a single
  70   return point. Do not abuse goto usage though... never goto up,
  71   never create more than one label and do not "gotoo far".
  72
  73
  74 CODE DOCUMENTATION
  75 ---------------------------------------------------------------------
  76
  77 * Add FIXME, TODO and XXX comments appropriately.
  78
  79 * Use Doxygen (http://www.stack.nl/~dimitri/doxygen/) to document your code
  80
  81 * Add your doxygen annotations in the header files. This allows other
  82   developers to read the documentation without having installed the source.
  83
  84 * Add simple READMEs and pictures as needed, but concentrate
  85   on doxygen.
  86
  87 CODE INSTRUMENTATION
  88 -----------------------------------------------------------------
  89
  90 Always:
  91     * Use const;
  92     * Use static for internal functions;
  93     * Use safe glib functions where possible;
  94     * Check validity of all received parameters;
  95     * Use osync_assert() while developing;
  96     * Do not use alloca() or other non-recommended functions;
  97     * Check for return errors even from malloc() and other
  98       standard system calls;
  99
 100 Regularly:
 101     * Use valgrind to profile you application and find memleaks
 102
 103 About header files:
 104     * Source code has to be split into modules, which are defined as
 105       a collection of implementation files (.c) with an interface
 106       exported through a header file (.h).
 107     * The inclusion (#include) of headers must reflect the dependencies
 108       between modules in the implementation. The most important
 109       implications from this statement are:
 110
 111         . implementation files (.c) *must* include *all* headers it
 112           directly depends;
 113         . implementation files (.c) *must not* include headers it
 114           doesn't directly depend;
 115         . headers should include headers only when needing a
 116           definition or declaration;
 117         . headers should never include other headers just to create a
 118           "single point of inclusion".
 119
 120       These rules may sound obvious, but they're actually hard to
 121       follow.
 122
 123
 124 COMMITS AND CHANGELOGS
 125 ---------------------------------------------------------------------
 126 Descriptive and small.
 127
 128 General rules:
 129    - *Always* do a svn diff and a svn status before a commit and
 130      document the diff(s) in the changelogs;
 131    - What matters is not what but why;
 132    - Several commits are usually better than a big one;
 133    - Do not commit unrelated modifications at once unless they're
 134      really trivial;
 135    - Commit ASAP.
 136
 137 BUILD-SYSTEM
 138 ---------------------------------------------------------------------
 139 Standard instructions:
 140
 141   Code should compile with no warnings, using the following GCC
 142   options:
 143
 144     -Wall
 145     -Werror
 146
 147     Recomended but not mandatory (for now):
 148     -W
 149     -Wmissing-declarations
 150     -Wmissing-prototypes
 151     -Wredundant-decls
 152     -Wshadow
 153     -Wbad-function-cast
 154     -Wcast-qual
 155     -std=iso9899:1990
 156     -D_FORTIFY_SOURCE=2
 157
 158     Hint:
 159     For developers using GCC there is a CMAKE_BUILD_TYPE "hacking" which sets
 160     the default compiler flags to a recommended compiler flag set.
 161
 162 LOGS and TRACES
 163 ---------------------------------------------------------------------
 164 There are two types of logs that must be handled by almost all
 165 applications:
 166
 167  * HIGH-LEVEL LOGS: these are standard, high-level logs usually
 168    enabled by default. Useful to advanced users, support-centers and
 169    alike. Should include basic information, including but not limited
 170    to:
 171      - start/end of application
 172      - errors
 173      - complex operations
 174
 175    The requirements document specifies if logs are needed or not.
 176
 177  * TRACES: traces are a particular kind of log used to debug the
 178    application. They're used mostly by black-box testers to submit
 179    failure reports.
 180
 181    Traces should be enabled in a per-application basis using an
 182    envinronment variable or at compile time, to be yet defined.
 183
 184 UNIT TESTS
 185 -----------------------------------------------------------------
 186
 187 * All code should be written together with unit-tests. The tool
 188   used to implement the tests is "check", available on
 189   http://check.sourceforge.net/.
 190
 191   The build-system infra-structure provides a configure option to
 192   allow check usage.
 193
 194   The tests must be implemented inside a sub-directory called test
 195   with the following modules:
 196
 197   check_<component name> --> the test-manager
 198   check_<unit name>      --> implements tests for interfaces
 199                              exported by unit
 200   check_<...>
 201
 202   Just to remember, an unit, or module, is a collection of
 203   souce-code files (.c) with an interface exported through
 204   a header file (.h).
 205
 206   All interfaces exported by units must be tested (that is,
 207   all non-static functions). The tests should implement at
 208   least the following test cases:
 209
 210     - standard usage
 211     - upper and bottom limits of buffers and variables as
 212       needed
 213     - error conditions
 214     - critical paths
 215
 216   Use incremental tests, that is, test functions before using them in
 217   other test-cases (for example, if you need to call function A to
 218   prepare the environment to test function B, test function A first).
 219
 220   Try to write the test-case before the unit or function itself.
 221
 222   If the test needs an external entity to work (for example, it needs
 223   a device connected on a specific port), put the test inside a
 224   condition for an environemnt variable and document it in a README
 225   file.