Add 'Compiler options & warnings' section.

Update Style section to be clearer about code alignment and show
some example code.
Other minor edits.



git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@4180 ea778897-0a13-0410-b9d1-a72fbfd435f5

ChangeLog

@@ -3,6 +3,11 @@
  * src/keybindings.c:
    Fix 'Reflow block' command when at the last paragraph and there's
    no last newline (patch by Eugene Arshinov, thanks).
+ * HACKING:
+   Add 'Compiler options & warnings' section.
+   Update Style section to be clearer about code alignment and show
+   some example code.
+   Other minor edits.
 
 
 2009-09-12  Nick Treleaven  <nick(dot)treleaven(at)btinternet(dot)com>

HACKING

@@ -48,12 +48,15 @@ If you're not using SVN, you can use the diff command::
 
 	$ diff -u originalpath modifiedpath > new-feature.patch
 
-Please make sure patches follow the style of existing code - In
-particular, use tabs for indentation. See `Style`_ and `Coding`_.
+.. note::
+    Please make sure patches follow the style of existing code - In
+    particular, use tabs for indentation. See `Coding`_.
+
+Windows tools
+-------------
+* Subversion (SVN): http://subversion.tigris.org/
+* diff, grep, etc: http://mingw.org/ or http://unxutils.sourceforge.net/
 
-For Windows:
-Subversion (SVN): http://subversion.tigris.org/
-diff, grep, etc: http://mingw.org/ or http://unxutils.sourceforge.net/.
 See also the 'Building on Windows' document on the website.
 
 File organization
@@ -91,7 +94,7 @@ for any changes to the plugin API, including appending elements.
 If you're in any doubt when making changes to plugin API code, just ask us.
 
 Plugin API/ABI design
----------------------
+^^^^^^^^^^^^^^^^^^^^^
 You should not make plugins rely on the size of a struct. This means:
 
 * Don't let plugins allocate any structs (stack or heap).
@@ -130,35 +133,88 @@ Coding
 * Don't write long functions with a lot of variables and/or scopes - break
   them down into smaller static functions where possible. This makes code
   much easier to read and maintain.
-* Use GLib types and functions - e.g. g_free instead of free.
+* Use GLib types and functions - gint not int, g_free() not free().
 * Your code should build against GLib 2.8 and GTK 2.8. At least for the
   moment, we want to keep the minimum requirement for GTK at 2.8 (of
   course, you can use the GTK_CHECK_VERSION macro to protect code using
   later versions).
-* We currently try to support the old GCC 2.9.x compiler,
-  so we always declare variables before statements. You can use
-  -Wdeclaration-after-statement in your ./configure CFLAGS to warn about
-  this.
-* You should also try to write ISO C90 code for portability, so always
+* Variables should be declared before statements. You can use
+  gcc's -Wdeclaration-after-statement to warn about this.
+* Don't let variable names shadow outer variables - use gcc's -Wshadow
+  option.
+
+Compiler options & warnings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Use ``CFLAGS='-Wfoo' ./configure`` or ``CFLAGS='-Wfoo' ./autogen.sh``
+to set warning options (as well as anything else e.g. -g -O2).
+
+* Enable warnings - for gcc use '-Wall -W' (and optionally
+  -Wno-unused-parameter to avoid unused parameter warnings in Glade
+  callbacks).
+* You should try to write ISO C90 code for portability, so always
   use C ``/* */`` comments and function_name(void) instead of
-  function_name().  This is for compatibility with various Unix-like
-  compilers. You can use -ansi in your CFLAGS to help check this.
+  function_name(). This is for compatibility with various Unix-like
+  compilers. You should use -ansi to help check this.
 
 Style
------
+^^^^^
 * We use a tab width of 4 and indent completely with tabs not spaces.
 * Use the multiline comment ``/* */`` to comment small blocks of code,
   functions descriptions or longer explanations of code, etc. C++ single
   line comments will cause portability issues. The more comments are in
-  your code the better.
+  your code the better. (See also ``scripts/fix-cxx-comments.pl`` in SVN).
 * Lines should not be longer than about 100 characters and after 100
-  characters the lines should be wrapped and more indented than the first
-  line to highlight that the line is continued.
+  characters the lines should be wrapped and indented once more to
+  show that the line is continued.
 * We don't put spaces between function names and the opening brace for
   argument lists.
-* Try to fit in with the existing code brace indenting style, comments,
-  operator spacing etc. It's not required for patches but it will save
-  us having to manually reformat them.
+* Variable declarations come first after an opening brace, then one
+  newline to separate declarations and code.
+* 2-operand operators should have a space each side.
+* Function bodies should have 2 blank newlines after them.
+* Align braces together on separate lines.
+* Don't put assignments in 'if/while/etc' expressions.
+* if statements without brace bodies should have the code on a separate
+  line, then a blank line afterwards.
+* Use braces after if/while statements if the body uses another
+  if/while statement.
+* Try to fit in with the existing code style.
+
+.. note::
+    A few of the above can be done with the SVN
+    ``scripts/fix-alignment.pl``, but it is quite dumb and it's much better
+    to write it correctly in the first place.
+
+.. below tabs should be used, but spaces are required for reST.
+
+Example::
+
+    gint some_func(void);
+
+
+    gint function_long_name(gchar arg1, <too many args to fit on this line>,
+            gchar argN)
+    {
+        gint foo;
+
+        if (foo)
+        {
+            gint dir = -1;    /* -1 to search backwards */
+
+            bar = foo;
+            if (bar != 7)
+                some_code(arg1, <too many args to fit on this line>,
+                    argN - 1, argN);
+
+            some_func();
+        }
+    }
+
+
+    gint another_function(void)
+    {
+        ...
+
 
 Libraries
 ---------