HACKING

   1 -------------------------------------------------------------------------------
   2 HACKING
   3 -------------------------------------------------------------------------------
   4
   5 Coding style
   6 ------------
   7
   8 This project is programmed using the Linux kernel coding style:
   9
  10   https://www.kernel.org/doc/html/latest/process/coding-style.html
  11
  12 Please use the same style for any code contributions, thanks!
  13
  14 In some exceptional cases deviations from the above coding guidelines are
  15 OK (in order to meet Qt/C++ related guidelines, for example).
  16
  17
  18 Contributions
  19 -------------
  20
  21  - In order to contribute you should ideally clone the git repository and
  22    let us know (preferably via IRC, or via the mailing list) from where to
  23    pull/review your changes. You can use github.com, or any other public git
  24    hosting site.
  25
  26  - Alternatively, patches can be sent to the development mailinglist at
  27    sigrok-devel@lists.sourceforge.net (please subscribe to the list first).
  28
  29    https://lists.sourceforge.net/lists/listinfo/sigrok-devel
  30
  31
  32 Random notes
  33 ------------
  34
  35  - Consistently use g_try_malloc() / g_try_malloc0(). Do not use standard
  36    malloc()/calloc() if it can be avoided (sometimes other libs such
  37    as libftdi can return malloc()'d memory, for example).
  38
  39  - Always properly match allocations with the proper *free() functions. If
  40    glib's g_try_malloc()/g_try_malloc0() was used, use g_free() to free the
  41    memory. Otherwise use standard free(). Never use the wrong function!
  42
  43  - Never use g_malloc() or g_malloc0(). These functions do not return nullptr
  44    if not enough memory is available but rather lead to an exit() or segfault
  45    instead. This behaviour is not acceptable.
  46    Use g_try_malloc()/g_try_malloc0() instead and check the return value.
  47
  48  - Use glib's gboolean / TRUE / FALSE for boolean types consistently.
  49    Do not use <stdbool.h> and its true / false, and do not invent private
  50    definitions for this either.
  51
  52  - Consistently use the same naming convention for #include guards in headers:
  53    <PROJECTNAME>_<PATH_TO_FILE>_<FILE>
  54    This ensures that all #include guards are always unique and consistent.
  55    Example: PULSEVIEW_PV_VIEW_RULER_H
  56
  57  - Consistently use the same naming convention for functions, if appropriate:
  58
  59    Getter/setter function names should usually end with "_get" or "_set".
  60    Functions creating new "objects" should end with "_new".
  61    Functions destroying "objects" should end with "_destroy".
  62    Functions adding or removing items (e.g. from lists) should end with
  63    either "_add" or "_remove".
  64    Functions operating on all items from a list (not on only one of them),
  65    should end with "_all", e.g. "_remove_all", "_get_all", and so on.
  66    Use "_remove_all" in favor of "_clear" for consistency.
  67
  68  - In Doxygen comments, put an empty line between the block of @param lines
  69    and the final @return line. The @param lines themselves (if there is more
  70    than one) are not separated by empty lines.
  71
  72  - Use QIcon::fromTheme() for icons that are included in the freedesktop.org
  73    icon naming specification. Do NOT use it for all other icons.
  74
  75
  76 Release engineering
  77 -------------------
  78
  79 See
  80
  81  http://sigrok.org/wiki/Developers/Release_process
  82
  83 for a list of items that need to be done when releasing a new tarball.
  84