[geany/geany] 34888d: Add some info about header includes to `HACKING` file

[Matthew Brush]

Branch:      refs/heads/master
Author:      Matthew Brush <matt at geany.org>
Committer:   Matthew Brush <matt at geany.org>
Date:        Wed, 21 May 2014 22:38:16 UTC
Commit:      34888d6bafd1df9ae2e3456b066c2b44ea676ae8
             https://github.com/geany/geany/commit/34888d6bafd1df9ae2e3456b066c2b44ea676ae8

Log Message:
-----------
Add some info about header includes to `HACKING` file


Modified Paths:
--------------
    HACKING

Modified: HACKING
72 lines changed, 72 insertions(+), 0 deletions(-)
===================================================================
@@ -302,6 +302,78 @@ Example::
     {
         ...
 
+Header Includes
+---------------
+
+In order to make including various headers in Geany more convenient, each
+file should include what it uses. If there is a file named ``foo.c``, and a
+file named ``foo.h``, it should be possible to include ``foo.h`` on its own
+without depending on stuff in ``foo.c`` that is included for the first time
+before ``foo.h``.
+
+Private Headers
+^^^^^^^^^^^^^^^
+
+If there is some data that needs to be shared between various parts of the
+core code, put them in a "private header", that is, if the public header is
+called ``foo.h``, then make a ``fooprivate.h`` header that contains the
+non-public functions, types, globals, etc that are needed. Other core source
+files can then just include the ``foo.h`` and/or ``fooprivate.h`` depending
+what they need, without exposing that stuff to plugins.
+
+Order of Includes
+^^^^^^^^^^^^^^^^^
+
+Inside a source file the includes section should be ordered like this:
+
+1. Always include the ``config.h`` file at the start of every source file,
+   for example::
+
+    #ifdef HAVE_CONFIG_H
+    # include "config.h"
+    #endif
+
+   This allows the Autotools and other build systems use the ``./configure``
+   time settings. If you don't do this, there's likely to be a number of
+   macros that you'll have to define in the build system or custom headers.
+
+   Warning: Never include ``config.h`` in headers, and especially in "public"
+   headers that plugins might include.
+
+2. Then include the header that has the same name as the source file (if
+   applicable). For example, for a source file named ``foo.c``, include
+   the ``foo.h`` below the ``config.h`` include. If there is a
+   ``fooprivate.h``, ``foo.c`` will most likely want to include that too,
+   put it in with includes in #3.
+
+3. At this point, it should be safe to include all the headers that declare
+   whatever is needed. If everything generally "includes what it uses" and
+   all files included contain the appropriate multiple-declaration guards
+   then the order of includes is fairly arbitrary. Prefer to use English
+   alphabetic order if possible.
+
+4. By now it doesn't really matter about the order, nothing below here is
+   "our problem". Semi-arbitrarily, you should use an include order like this:
+
+    1. Standard C headers
+    2. Non-standard system headers (eg. ``windows.h`` or ``unistd.h``)
+    3. GLib/GTK+ or related headers
+
+5. Everything else that should not influence 1-4.
+
+Including in Header Files
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Headers should also include what they use. All of the types should defined in
+order to allow the header to be included stand-alone. For example, if a
+header uses a ``GtkWidget*``, it should ``#include <gtk/gtk.h>``. Or, if a
+headers uses a ``GPtrArray*``, it should ``#include <glib.h>`` to ensure that
+all of the types are declared, whether by pointers/opaquely or fully, as
+required. Since all headers will use a ``G_BEGIN_DECLS`` and ``G_END_DECLS``
+guard for C++, the bare minimum for a header is to include ``glib.h`` or
+``<gtk/gtk.h>`` or ``gtkcompat.h`` or some other header that makes those
+macros available.
+
 
 Committing
 ----------



--------------
This E-Mail was brought to you by github_commit_mail.py (Source: https://github.com/geany/infrastructure).