HACKING

   1 -------------------------------------------------------------------------------
   2 HACKING
   3 -------------------------------------------------------------------------------
   4
   5 Coding style
   6 ------------
   7
   8 This project is programmed using the Linux kernel coding style, see
   9 http://lxr.linux.no/linux/Documentation/CodingStyle for details.
  10
  11 Please use the same style for any code contributions, thanks!
  12
  13
  14 Contributions
  15 -------------
  16
  17  - Patches should be sent to the development mailinglist at
  18    sigrok-devel@lists.sourceforge.net (please subscribe to the list first).
  19
  20    https://lists.sourceforge.net/lists/listinfo/sigrok-devel
  21
  22  - Alternatively, you can also clone the git repository and let us know
  23    from where to pull/review your changes. You can use gitorious.org,
  24    github.com, or any other public git hosting site.
  25
  26
  27 Random notes
  28 ------------
  29
  30  - Consistently use g_try_malloc() / g_try_malloc0(). Do not use standard
  31    malloc()/calloc() if it can be avoided (sometimes other libs such
  32    as libftdi can return malloc()'d memory, for example).
  33
  34  - Always properly match allocations with the proper *free() functions. If
  35    glib's g_try_malloc()/g_try_malloc0() was used, use g_free() to free the
  36    memory. Otherwise use standard free(). Never use the wrong function!
  37
  38  - Never use g_malloc() or g_malloc0(). These functions do not return NULL
  39    if not enough memory is available but rather lead to an exit() or segfault
  40    instead. This behaviour is not acceptable for libraries.
  41    Use g_try_malloc()/g_try_malloc0() instead and check the return value.
  42
  43  - You should never print any messages (neither to stdout nor stderr nor
  44    elsewhere) "manually" via e.g. printf() or g_log() or similar functions.
  45    Only sr_err()/sr_warn()/sr_info()/sr_dbg()/sr_spew() should be used.
  46
  47  - Use glib's gboolean / TRUE / FALSE for boolean types consistently.
  48    Do not use <stdbool.h> and its true / false, and do not invent private
  49    definitions for this either.
  50
  51  - Consistently use the same naming convention for #include guards in headers:
  52    <PROJECTNAME>_<PATH_TO_FILE>_<FILE>
  53    This ensures that all #include guards are always unique and consistent.
  54    Examples: LIBSIGROK_LIBSIGROK_H, LIBSIGROK_HARDWARE_ASIX_SIGMA_ASIX_SIGMA_H
  55
  56  - Consistently use the same naming convention for API functions:
  57    <libprefix>_<groupname>_<action>().
  58
  59    Examples:
  60      sr_log_loglevel_set(), sr_log_loglevel_get(), sr_log_handler_set(),
  61      sr_log_handler_set_default(), and so on.
  62    Or:
  63      sr_session_new(), sr_session_destroy(), sr_session_load(), and so on.
  64
  65    Getter/setter function names should usually end with "_get" or "_set".
  66    Functions creating new "objects" should end with "_new".
  67    Functions destroying "objects" should end with "_destroy".
  68    Functions adding or removing items (e.g. from lists) should end with
  69    either "_add" or "_remove".
  70    Functions operating on all items from a list (not on only one of them),
  71    should end with "_all", e.g. "_remove_all", "_get_all", and so on.
  72    Use "_remove_all" in favor of "_clear" for consistency.
  73
  74
  75 Doxygen
  76 -------
  77
  78  - In Doxygen comments, put an empty line between the block of @param lines
  79    and the final @return line. The @param lines themselves (if there is more
  80    than one) are not separated by empty lines.
  81
  82  - Mark private functions (SR_PRIV) with /** @private */, so that Doxygen
  83    doesn't include them in the output. Functions that are "static" anyway
  84    don't need to be marked like this.
  85
  86  - Mark private variables/#defines with /** @cond PRIVATE */ and
  87    /** @endcond */, so that Doxygen doesn't include them in the output.
  88    Variables that are "static" don't need to be marked like this.
  89
  90
  91 Release engineering
  92 -------------------
  93
  94 See
  95
  96  http://sigrok.org/wiki/Developers/Release_process
  97
  98 for a list of items that need to be done when releasing a new tarball.
  99