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
  15 Contributions
  16 -------------
  17
  18  - In order to contribute you should ideally clone the git repository and
  19    let us know (preferably via IRC, or via the mailing list) from where to
  20    pull/review your changes. You can use github.com, or any other public git
  21    hosting site.
  22
  23  - Alternatively, patches can be sent to the development mailinglist at
  24    sigrok-devel@lists.sourceforge.net (please subscribe to the list first).
  25
  26    https://lists.sourceforge.net/lists/listinfo/sigrok-devel
  27
  28
  29 Random notes
  30 ------------
  31
  32  - Don't do variable declarations in compound statements, only at the
  33    beginning of a function.
  34
  35  - Generally avoid assigning values to variables at declaration time,
  36    especially so for complex and/or run-time dependent values.
  37
  38  - Consistently use g_*malloc() / g_*malloc0(). Do not use standard
  39    malloc()/calloc() if it can be avoided (sometimes other libs such
  40    as libftdi can return malloc()'d memory, for example).
  41
  42  - Always properly match allocations with the proper *free() functions. If
  43    glib's g_*malloc()/g_*malloc0() was used, use g_free() to free the
  44    memory. Otherwise use standard free(). Never use the wrong function!
  45
  46  - We assume that "small" memory allocations (< 1MB) will always succeed.
  47    Thus, it's fine to use g_malloc() or g_malloc0() for allocations of
  48    simple/small structs and such (instead of using g_try_malloc()), and
  49    there's no need to check the return value.
  50
  51    Do use g_try_malloc() or g_try_malloc0() for large (>= 1MB) allocations
  52    and check the return value.
  53
  54  - You should never print any messages (neither to stdout nor stderr nor
  55    elsewhere) "manually" via e.g. printf() or g_log() or similar functions.
  56    Only sr_err()/sr_warn()/sr_info()/sr_dbg()/sr_spew() should be used.
  57
  58  - Use glib's gboolean / TRUE / FALSE for boolean types consistently.
  59    Do not use <stdbool.h> and its true / false, and do not invent private
  60    definitions for this either.
  61
  62  - Consistently use the same naming convention for #include guards in headers:
  63    <PROJECTNAME>_<PATH_TO_FILE>_<FILE>
  64    This ensures that all #include guards are always unique and consistent.
  65    Example: SIGROK_CLI_SIGROK_CLI_H
  66
  67  - Consistently use the same naming convention for functions, if appropriate:
  68
  69    Getter/setter function names should usually end with "_get" or "_set".
  70    Functions creating new "objects" should end with "_new".
  71    Functions destroying "objects" should end with "_destroy".
  72    Functions adding or removing items (e.g. from lists) should end with
  73    either "_add" or "_remove".
  74    Functions operating on all items from a list (not on only one of them),
  75    should end with "_all", e.g. "_remove_all", "_get_all", and so on.
  76    Use "_remove_all" in favor of "_clear" for consistency.
  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
  83 Release engineering
  84 -------------------
  85
  86 See
  87
  88  http://sigrok.org/wiki/Developers/Release_process
  89
  90 for a list of items that need to be done when releasing a new tarball.
  91