[gedit] Write programming best practices to the hacking file

[Sébastien Wilmet <swilmet src gnome org>]

commit 0d71e701ce58d4a5187a8b0200b9f1ef00f50b16
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Wed Jan 8 23:30:49 2014 +0100

    Write programming best practices to the hacking file
    
    And add a few more code conventions and links.

 HACKING |   78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 76 insertions(+), 2 deletions(-)
---
diff --git a/HACKING b/HACKING
index a816d47..cfee999 100644
--- a/HACKING
+++ b/HACKING
@@ -37,7 +37,7 @@ Commit guidelines
 =================
 
 Please don't commit directly to the git repository unless
-you have been given the green light to commit freely to gedit. 
+you have been given the green light to commit freely to gedit.
 When in doubt assume you haven't ;-).
 
 Please attach patches in bugzilla (http://bugzilla.gnome.org).
@@ -52,7 +52,7 @@ fix typos in the code, etc.
 Please send patches for build & configure fixes too.  I really appreciate
 your help, I just want to review these fixes before applying.
 
-If you are a "build sheriff", feel free to commit fixes for build and 
+If you are a "build sheriff", feel free to commit fixes for build and
 configure (please, send me an e-mail with the patch you have applied).
 
 When committing to the gedit git repository make sure to include a
@@ -102,6 +102,78 @@ conventions, but for new code it is better to follow them, for consistency.
 
   - Follow the C89 standard. In particular, no "//"-style comments.
 
+  - As a general rule of thumb, follow the same coding style as the surrounding
+    code.
+
+  - Do not be cheap about blank lines, spacing the code vertically help
+    readability. However never use two consecutive blank lines, there is really
+    no need.
+
+
+Programming best practices
+==========================
+
+gedit is a pretty big piece of software, developed over the years by different
+people and GNOME technologies. Some parts of the code may be a little old. So
+when editing the code, we should try to make it better, not worse.
+
+Here are some general advices.
+
+  - Simplicity: the simpler code the better. Any trick that seem smart when you
+    write it is going to bite your ass later when reading the code. Given that
+    you spend 90% of the time staring at the code and 10% writing it, making
+    reading the code harder is a net loss.
+
+  - Brevity: make an effort to refactor common code into utility functions and
+    use library function whenever is possible: every time you cut and paste a
+    line of code you are throwing away all the precious seconds of your life
+    that you will later spend trying to figure out the differences among the two
+    copies that will have surely diverged.
+
+  - Code for change: code is bound to contain bugs no matter how well it is
+    written. A good coding style allows to fix these bugs with minimal changes
+    instead of reformatting a whole section of unrelated code, this is
+    especially important to make patch review easier and to easily understand
+    the commit history. Some practical examples are:
+
+      - Factor code into self contained functions so that changing a function
+       does not require to change all the callers.
+
+      - Do not align variable declaration, "case" statements etc, since this
+       will inevitably mean that when a line will change you'll have to
+       reformat all the surrounding ones.
+
+      - Declare variables in the strictest scope as possible.
+
+      - Reorder functions so that you do not need prototypes for static
+       functions so that when you change them you need to change them only in
+       one place.
+
+  - Self documentation and code comments: use code comments parsimoniously. Code
+    should be written so that it is clear and evident without the need of
+    comments. Besides, comments usually get outdated when the code is changed
+    and they become misleading. In particular avoid stating the obvious e.g. "a
+    = 1; /* assign 1 to a */". Use good function names and variables to make the
+    code self-documented.
+
+    A good function name is one that explain clearly all what its code really
+    does. There shouldn't be hidden features. If you can not find easily a good
+    function name, you should probably split the function in smaller pieces. A
+    function should do only one thing, but do it well.
+
+    Please avoid lots of one-letter variables. And a variable should be used for
+    only one purpose.
+
+    Self-documentation is obviously not always possible, so when a comment is
+    needed, it is needed. In those cases make sure to explain why and not only
+    how a specific thing is done: you can deduce the "how" from the code, but
+    not the "why".  Public library functions should always be documented and in
+    particular should include the calling conventions, e.g. if the result should
+    be freed by the caller.
+
+    Do not use fancy frames around comments like a line full of
+    /*---------------*/ etc.
+
 
 See also
 ========
@@ -109,6 +181,8 @@ See also
 https://wiki.gnome.org/Apps/Gedit/DevGettingStarted
 https://wiki.gnome.org/Projects/GTK%2B/BestPractices
 ftp://ftp.gnome.org/pub/GNOME/teams/docs/devel/guides/programming_guidelines/
+http://ometer.com/hacking.html
+http://blogs.gnome.org/swilmet/2012/08/01/about-code-quality-and-maintainability/
 
 
 Thanks,