1 files changed, 113 insertions, 0 deletions
diff --git a/HACKING b/HACKING
new file mode 100644
index 00000000..dc02f5ee
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,113 @@
+Formatting
+==========
+
+All parts of Pango other than modules should use the following formatting
+style; for modules, it is up to the discretion of the module 
+author / maintainer, though they are encouraged to follow the following.
+
+The Pango formatting style is basically the GNU style of formatting
+(see http://www.gnu.org/prep/standards.html), with a few additions.
+In brief overview:
+
+ - Two character indents are used; braces go on a separate line, and 
+   get a separate indentation level, so the total indent for an
+   enclosed block is 4 characters.
+
+    if (x < foo (y, z))
+      haha = bar[4] + 5;
+    else
+      {
+	while (z)
+	  {
+	    haha += foo (z, z);
+	    z--;
+	  }
+	return abc (haha);
+      }
+
+ - Spaces should be present between function name and argument block,
+   and after commas.
+
+     foo (z, z)
+
+ - In pointer types, the '*' is grouped with the variable name,
+   not with the base type. 
+
+    int *a;
+
+   NOT: 'int* a'.
+
+   In cases where there is no variable name, for instance, return
+   values, there should be a single space between the base type 
+   and the '*'.
+
+ - function and variable names are lower_case_with_underscores
+   type names are StudlyCaps, macro names are UPPER_CASE_WITH_UNDERSCORES
+
+
+Documentation comments
+======================
+
+All public API functions should have inline documentation headers
+in the gtk-doc / gnome-doc style. For instance:
+
+/**
+ * pango_layout_get_line:
+ * @layout: a #PangoLayout
+ * @line: the index of a line, which must be between 0 and
+ *        pango_layout_get_line_count(layout) - 1, inclusive.
+ * 
+ * Retrieves a particular line from a #PangoLayout (or @layout.)
+ * 
+ * Return value: the requested #PangoLayoutLine, or %NULL if the
+ *               index is out of range. This layout line can
+ *               be ref'ed and retained, but will become invalid
+ *               if changes are made to the #PangoLayout.
+ *
+ * Since: 1.6
+ **/
+PangoLayoutLine *
+pango_layout_get_line (PangoLayout *layout,
+		       int          line)
+[...]
+
+
+Choosing Function Names
+=======================
+
+- Don't abbreviate in unexpected ways:
+
+    pango_layout_get_line_count ()
+
+  Not:
+
+    pango_layout_ln_cnt ()
+
+- function that retrieve a value in a side-effect free fashion, should
+  include "get" in the name.
+
+    int pango_layout_get_line_count (PangoLayout *layout)
+
+  not 
+
+    pango_layout_line_count ()
+
+
+- functions that set a single parameter in a side-effect free fashion
+  should include "set" in the name, for instance:
+
+  void pango_layout_set_width (PangoLayout    *layout,
+			       int             width);
+
+Other comments
+==============
+
+- Avoid unsigned values for all but flags fields. This is because
+  the way C handles unsigned values generates bugs like crazy:
+
+  If width is unsigned and 10, then:
+
+   int new_width = MAX (width - 15, 1);
+
+  produces 4294967291, not 1.
+