"SfR Fresh" - the SfR Freeware/Shareware Archive

Member "pango-1.20.5/HACKING" of archive pango-1.20.5.tar.gz:

    1 Formatting
    2 ==========
    3 
    4 All parts of Pango other than modules should use the following formatting
    5 style; for modules, it is up to the discretion of the module 
    6 author / maintainer, though they are encouraged to follow the following.
    7 
    8 The Pango formatting style is basically the GNU style of formatting
    9 (see http://www.gnu.org/prep/standards.html), with a few additions.
   10 In brief overview:
   11 
   12  - Two character indents are used; braces go on a separate line, and 
   13    get a separate indentation level, so the total indent for an
   14    enclosed block is 4 characters.
   15 
   16     if (x < foo (y, z))
   17       haha = bar[4] + 5;
   18     else
   19       {
   20 	while (z)
   21 	  {
   22 	    haha += foo (z, z);
   23 	    z--;
   24 	  }
   25 	return abc (haha);
   26       }
   27 
   28  - Spaces should be present between function name and argument block,
   29    and after commas.
   30 
   31      foo (z, z)
   32 
   33  - In pointer types, the '*' is grouped with the variable name,
   34    not with the base type. 
   35 
   36     int *a;
   37 
   38    NOT: 'int* a'.
   39 
   40    In cases where there is no variable name, for instance, return
   41    values, there should be a single space between the base type 
   42    and the '*'.
   43 
   44  - function and variable names are lower_case_with_underscores
   45    type names are StudlyCaps, macro names are UPPER_CASE_WITH_UNDERSCORES
   46 
   47 
   48 Documentation comments
   49 ======================
   50 
   51 All public API functions should have inline documentation headers
   52 in the gtk-doc / gnome-doc style. For instance:
   53 
   54 /**
   55  * pango_layout_get_line:
   56  * @layout: a #PangoLayout
   57  * @line: the index of a line, which must be between 0 and
   58  *        pango_layout_get_line_count(layout) - 1, inclusive.
   59  * 
   60  * Retrieves a particular line from a #PangoLayout (or @layout.)
   61  * 
   62  * Return value: the requested #PangoLayoutLine, or %NULL if the
   63  *               index is out of range. This layout line can
   64  *               be ref'ed and retained, but will become invalid
   65  *               if changes are made to the #PangoLayout.
   66  *
   67  * Since: 1.6
   68  **/
   69 PangoLayoutLine *
   70 pango_layout_get_line (PangoLayout *layout,
   71 		       int          line)
   72 [...]
   73 
   74 
   75 Choosing Function Names
   76 =======================
   77 
   78 - Don't abbreviate in unexpected ways:
   79 
   80     pango_layout_get_line_count ()
   81 
   82   Not:
   83 
   84     pango_layout_ln_cnt ()
   85 
   86 - function that retrieve a value in a side-effect free fashion, should
   87   include "get" in the name.
   88 
   89     int pango_layout_get_line_count (PangoLayout *layout)
   90 
   91   not 
   92 
   93     pango_layout_line_count ()
   94 
   95 
   96 - functions that set a single parameter in a side-effect free fashion
   97   should include "set" in the name, for instance:
   98 
   99   void pango_layout_set_width (PangoLayout    *layout,
  100 			       int             width);
  101 
  102 Other comments
  103 ==============
  104 
  105 - Avoid unsigned values for all but flags fields. This is because
  106   the way C handles unsigned values generates bugs like crazy:
  107 
  108   If width is unsigned and 10, then:
  109 
  110    int new_width = MAX (width - 15, 1);
  111 
  112   produces 4294967291, not 1.
  113