HACKING

   1 * Don't commit directly, instead send your diff to the authors (use
   2   'cvs diff -Nu').
   3
   4 Working in libgsf
   5 -------------------
   6
   7    When writing libgsf our priorities are
   8
   9         1) Correctness.
  10         2) Maintainable & Documented
  11         3) Modular and well designed
  12         and a distant
  13         4) portable
  14         5) Fast
  15
  16     When you submit code to inclusion in libgsf, or when you modify the sources
  17 directly on the Git repository, please keep those things in mind.  While
  18 performance is important please note that we do not want to hand tune code
  19 to shave milliseconds at this point.  Well designed algorithms and data
  20 strucutures are fertile areas for development, obfuscated code to make a
  21 loop 3% faster is not.  Specifically, this means:
  22
  23         - Clarity of design and function are paramount
  24         - Make sure your code does not generate warnings at all.
  25         - Please follow the formatting style
  26
  27 Formatting style
  28 ----------------
  29
  30    The formatting style of libgsf is a mix of various styles, make
  31 yourself familiar with the GNU coding standards (shipped with most
  32 GNU/Linux systems as the standards.info file), then read the Linux
  33 kernel coding standards and ignore Linus' jokes.  Then look at the
  34 Gtk+ header files to get acquainted on how to write nice header files
  35 that are almost self documenting.
  36
  37    Remember: Use 8 space tabs for indentation: that will keep your
  38 code honest as you will be forced to split your routines in more
  39 modular chunks (as detailed by Linus).
  40
  41    Emacs users can get the default indentation style with this:
  42   (set-c-style "K&R")
  43   (setq c-basic-offset 8)
  44
  45    On top of that, you will have to:
  46
  47         - Follow the Gtk+ cleanliness conventions for function
  48           prototypes.
  49
  50         - Follow the Gtk+ namespace convention for function names.
  51           module_submodule_operation
  52
  53         - Make sure your code does not have a single warning (with the
  54           default strong warnings that Gnumeric compiles with) before
  55           your code is submitted. (Although we do not advocate -Werror)
  56
  57         - Every entry point to a public routine should use the
  58           g_return_if_fail and g_return_val_if_fail macros to verify
  59           that the parameters passed are valid.
  60
  61         - Under no circumstances use magic variables.  Use typedef
  62           enum { ... } type; to create enumerations.  Do not use
  63           integers to hold references to enumerations, the compiler
  64           can help catch various errors.
  65
  66         - Use g_warning to mark spots that need to be reviewed or are
  67           not finished to let me fix it eventually.
  68
  69         - Do not submit code that is just a temporary workaround for a
  70           full fledged feature.  i.e. don't submit a quick hack at
  71           "search text" which is not designed to be expanded upon.  We
  72           do not want to maintain limited features.  It is better submit an
  73           implementation that has been designed to be expanded and enhanced,
  74           even if it is not completely finished.
  75
  76         - It is more important to be correct than to be fast.
  77
  78         - Do not optimize unnecessarily.  Do profile, do look for the
  79           weak spots before applying "optimization by feeling".  This
  80           is not a Ouija-based project.
  81
  82         - It is more important to keep the code maintainable and
  83           readable than to be fast.  If you have a great idea about
  84           optimizing the code, make sure it is implemented cleanly,
  85           that there is a clean and maintainable way to do it:
  86
  87         - Fast code that is difficult to maintain has no place in
  88           Gnumeric and will be dropped.
  89
  90         - Follow the libgsf commenting style, which is not the Gtk
  91           style;
  92                 /* ie. use this for
  93                  * multi-line comments
  94                  */
  95
  96    All of this is to ensure the libgsf code will be kept within
  97 reasonable margins of maintainability for the future: Remember, in two years
  98 you will probably be far too busy to maintain your own contributions, and they
  99 might become a burden to the program maintainers.
 100
 101    libgsf is intended to be a foundation for a various document centric
 102 projects.
 103
 104    Cleaning code in libgsf is more important than trying not to break
 105 existing code.  By all means, code clean ups are always welcome.