GNOME Games Coding Style
========================

The coding style to respect in this project is very similar to most
Vala projects.

 * 4-spaces wide tabs (and not spaces) for indentation.

 * Spaces for alignment.

 * ''Prefer'' lines of less than <= 80 columns

 * 1-space between function name and braces (both calls and signature
   declarations)

 * Avoid the use of the 'this' keyword when possible.

 * If function signature/call fits in a single line, do not break it
   into multiple lines.

 * For methods/functions that take variable argument tuples, all the
   first elements of tuples are indented normally with the subsequent
   elements of each tuple indented 4-spaces more. Like this:

        action.get ("ObjectID",
                        typeof (string),
                        out this.object_id,
                    "Filter",
                        typeof (string),
                        out this.filter,
                    "StartingIndex",
                        typeof (uint),
                        out this.index,
                    "RequestedCount",
                        typeof (uint),
                        out this.requested_count,
                    "SortCriteria",
                        typeof (string),
                        out this.sort_criteria);

 * ''Prefer'' descriptive names over abbreviations (unless well-known)
   & shortening of names. E.g. discoverer over disco.

 * Use 'var' in variable declarations wherever possible.

 * Don't use var when declaring a number from a literal.

 * Use 'as' to cast wherever possible.

 * Single statements inside if/else must not be enclosed by '{}'.

 * The more you provide docs in comments, but at the same time avoid
   over-documenting. Here is an example of useless comment:

   // Fetch the document
   fetch_the_document ();

 * Each class should go in a separate .vala file & named according to
   the class in it, in spinal-case. E.g. Games.GameSource class should
   go under game-source.vala.

 * Don't use any 'using' statement.

 * Declare the namespace(s) of the class/errordomain with the
   class/errordomain itself. Like this:

   private class Games.Hello {
       ...
   };

 * Prefer 'foreach' over 'for'.

 * Use GObject-Style construction whenever possible.

 * Prefer properties over methods whenever possible.

 * Declare properties getters before the setters.

 * Add a newline to break the code in logical pieces.

 * Add a newline before each return, throw, break, continue etc. if
   it is not the only statement in that block.

   if (condition_applies ()) {
       do_something ();

       return false;
   }

   if (other_condition_applies ())
       return true;

   Except for the break in a switch:

   switch (val) {
   case 1:
       debug ("case 1");
       do_one ();
       break;

   default:
       ...
   }

 * Give the 'case' statements the same indentation level as their
   'switch' statement.

 * Add a newline at the end of each file.

 * If a function returns several equally important values, they should
   all be given as out arguments. In other words, prefer this:

   void get_a_and_b (out string a, out string b)

   rather than the un-even, string get_a_and_b (out string b)

 * Use methods as callbacks to signals.

 * ''Prefer'' operators over methods when possible. E.g. prefer
   'collection[key]' over 'collection.get(key)'.

 * If a function or a method can be used as a callback, don't enclose
   it in a lambda. E.g. do 'do (callback)' rather than
   'do (() => callback ())'.

 * Limit the try blocks to the code throwing the error.

 * Anything that can be 'private' must be 'private'.

 * Avoid usage of the 'protected' visibility.

 * Use the 'internal' visibility carefully.

 * Always add a comma after the enumerated value of an enum type.

 * Always add a comma after the final error code of an errordomain type.

 * Any 'else', 'else if', 'catch' block or any other special block
   following another one should start in its own line and not on the
   same as the previous closing brace.

 * Internationalize error messages, which implies using printf style
   string construction rather than string templates.

 * Append the original error message to the one you are building when
   refining an error.

For C code, the following rules apply, inspired by several other GObject
projects.

 * 2 spaces for indentation.

 * ''Prefer'' lines of less than <= 80 columns

 * Functions with no parameters should state it with the 'void' keyword.

 * In C files, function definitions are split into lines that way:
    * modifiers and the returned type at the beginning of the line;
    * the function name and the first parameter (if any) at the
      beginning of the line;
    * each extra parameter has its own line, aligned with the first
      parameter;
    * the opening curly brace at the beginning of the line.

 * In header files, function definitions are split into lines that way:
    * modifiers, the returned type, the function name and the first
      parameter (if any) at the beginning of the line;
    * each extra parameter has its own line, aligned with the first
      parameter;
    * the opening curly brace at the beginning of the line.

 * No nested functions, make them static instead.

 * 1-space between function name and braces (both calls and signature).

 * ''Prefer'' descriptive names over abbreviations (unless well-known)
   & shortening of names. E.g. discoverer over disco.

 * No single statement blocks.

 * The more you provide docs in comments, but at the same time avoid
   over-documenting. Here is an example of useless comment:

   // Fetch the document
   fetch_the_document ();

 * Each class should go in a separate .c and .h file & named according
   to the class in it, in spinal-case. E.g. Games.GameSource class should
   go under game-source.h and game-source.c.

 * Add a newline to break the code in logical pieces.

 * Add a newline before each return, break, continue etc. if it is not
   the only statement in that block.

   if (condition_applies (self)) {
       do_something (self);

       return FALSE;
   }

   if (other_condition_applies ())
       return TRUE;

 * Give the 'case' statements the same indentation level as their
   'switch' statement.

 * Add a newline at the end of each file.

 * If a function returns several equally important values, they should
   all be given as out arguments. In other words, prefer this:

   void get_a_and_b (gchar **a, gchar **b)

   rather than the un-even, gchar *get_a_and_b (gchar **b)

 * Anything that can be 'private' (static to the C file) must be
   'private'.

 * Always add a comma after the enumerated value of an enum type broken
   into multiple lines.

 * Always add a comma after values of an array literal broken into
   multiple lines.

 * Any 'else', 'else if' block or any other special block following
   another one should start in its own line and not on the same as the
   previous closing brace.

 * Append the original error message to the one you are building when
   refining an error.
