Improve HACKING file

1 files changed, 73 insertions, 64 deletions

diff --git a/HACKING b/HACKING
index ee36d080..d92dc9f3 100644
--- a/HACKING
+++ b/HACKING
@@ -14,12 +14,12 @@ directly unless you have been given the green light to commit freely to
 GtkSourceView. When in doubt assume you haven't ;-).
 
 People who can commit freely to GtkSourceView:
-* GtkSourceView maintainers, with of course discussion before doing important
-  changes.
+* GtkSourceView maintainers (or sub-maintainers in their area of expertise),
+  with of course discussion before doing important changes.
 * GNOME "build sheriffs", to fix build issues.
 
-Code conventions
-----------------
+C code conventions
+------------------
 
 You may encounter old code that doesn't follow all the following code
 conventions, but for new code it is better to follow them, for consistency.
@@ -28,103 +28,112 @@ conventions, but for new code it is better to follow them, for consistency.
 
   - Indent the C code with tabulations with a width of eight characters.
 
-  - The files should have a modeline for the indentation style.
-
   - All blocks should be surrounded by curly braces, even one-line blocks. The
-    curly braces must be placed on their own lines. It spaces out the code, to
-    have a better readability. And when modifying a block of code, if it
-    switches between one and two lines, we don't need to add/remove the curly
-    braces all the time.
+    curly braces must be placed on their own lines. Like this:
+
+	if (foo)
+	{
+		call_foo ();
+	}
+	else
+	{
+		call_bar ();
+	}
+
+    Rationale: it spaces out the code, to have a better readability. And when
+    modifying a block of code, if it switches between one and two lines, we
+    don't need to add/remove the curly braces all the time.
 
   - Follow the C89 standard. In particular, no "//"-style comments.
 
-  - As a general rule of thumb, follow the same coding style as the surrounding
-    code.
+  - The files should have a modeline for the indentation style.
 
   - Do not be cheap about blank lines, spacing the code vertically helps
     readability. However never use two consecutive blank lines, there is really
     no need.
 
-Programming best practices
+  - As a general rule of thumb, follow the same coding style as the surrounding
+    code.
+
+Programming best-practices
 --------------------------
 
-GtkSourceView is a pretty big piece of software, developed over the years by
+GtkSourceView is a sizeable 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.
+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 and variable names to make
-    the code self-documented.
+    write it is going to bite your ass later when reading the code. In fact, a
+    code is read far more often than it is written: for fixing a bug, adding a
+    feature, or simply see how it is implemented. So making the code harder to
+    read is a net loss.
+
+  - Avoid code duplication, make an effort to refactor common code into utility
+    functions.
+
+  - Write self-documented code when possible: instead of writing comments, it
+    is often possible to make the code self-documented by choosing good names
+    for the variables, functions and types.
+
+    Please avoid lots of one-letter variable names, it makes the code hard to
+    understand. Don't be afraid to write long variable names. Also, a variable
+    should be used for only one purpose.
 
     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.
+  - About comments:
+
+    Do not write comments to state the obvious, for example avoid:
+    i = 0; /* assign 0 to i */
+
+    Of course, write GTK-Doc comments to document the public API, especially
+    the class descriptions. The class descriptions gives a nice overview when
+    someone discovers the library.
+
+    For a private class, it is useful to write a comment at the top describing
+    in a few lines what the class does.
+
+    Document well the data structures: the invariants (what is or should be
+    always true about certain data fields); for a list, what is the element
+    type; for a hash table, what are the key and value types; etc. It is more
+    important to document the data structures than the functions, because when
+    understanding well the data structures, the functions implementation should
+    be for the most part obvious.
 
-    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.
+    When it isn't obvious, it is more important to explain *why* something is
+    implemented in this way, not the *how*. You can deduce the *how* from the
+    code, but not the *why*.
 
-    Do not use fancy frames around comments like a line full of
-    /*---------------*/ etc.
+    If a non-trivial feature was previously implemented in a different way,
+    it's useful to write a comment to describe in a few lines the previous
+    implementation(s), and why it has been changed (for example to fix some
+    problems). It permits to avoid repeating history, otherwise a new developer
+    might wonder why a certain feature is implemented in "this complicated way"
+    and not in "that simpler obvious way". For such things, a comment in the
+    code has more chances to be read than an old commit message (especially if
+    the code has been copied from one repository to another).
 
   - Contribute below on the stack. Fix a problem at the right place, instead of
-    writing hacks to work around a bug or a lack of feature in an underlying
-    library.
+    writing hacks or heuristics to work around a bug or a lack of feature in an
+    underlying library.
 
 See also
 --------
 
-https://wiki.gnome.org/Apps/Gedit/DevGettingStarted
 https://developer.gnome.org/programming-guidelines/stable/
 https://wiki.gnome.org/Projects/GTK%2B/BestPractices
+https://wiki.gnome.org/Projects/GLib/CompilerRequirements
 http://ometer.com/hacking.html
 https://blogs.gnome.org/swilmet/2012/08/01/about-code-quality-and-maintainability/
 
 For a shared library:
 
 http://davidz25.blogspot.be/2011/07/writing-c-library-intro-conclusion-and.html
-http://akkadia.org/drepper/
+http://akkadia.org/drepper/ (Ulrich Drepper):
 	- How to Write Shared Libraries
 	- Good Practices in Library Design, Implementation, and Maintenance