CodingStyle.txt 6.92 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
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)

16
 * Avoid the use of the 'this' keyword when possible.
17 18 19 20 21 22

 * 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
23
   elements of each tuple indented 4-spaces more. Like this:
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41

        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)
42
   & shortening of names. E.g. discoverer over disco.
43 44 45

 * Use 'var' in variable declarations wherever possible.

46
 * Don't use var when declaring a number from a literal.
Adrien Plazas's avatar
Adrien Plazas committed
47

48 49
 * Use 'as' to cast wherever possible.

50
 * Single statements inside if/else must not be enclosed by '{}'.
51 52 53 54 55 56 57 58

 * 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
59
   the class in it, in spinal-case. E.g. Games.GameSource class should
60 61
   go under game-source.vala.

Adrien Plazas's avatar
Adrien Plazas committed
62
 * Don't use any 'using' statement.
63 64 65 66 67 68 69 70 71 72 73 74 75 76

 * 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.

77
 * Declare properties getters before the setters.
78 79 80

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

Adrien Plazas's avatar
Adrien Plazas committed
81 82
 * Add a newline before each return, throw, break, continue etc. if
   it is not the only statement in that block.
83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110

   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
111
   all be given as out arguments. In other words, prefer this:
112 113 114 115

   void get_a_and_b (out string a, out string b)

   rather than the un-even, string get_a_and_b (out string b)
Adrien Plazas's avatar
Adrien Plazas committed
116 117 118

 * Use methods as callbacks to signals.

119
 * ''Prefer'' operators over methods when possible. E.g. prefer
Adrien Plazas's avatar
Adrien Plazas committed
120 121 122
   'collection[key]' over 'collection.get(key)'.

 * If a function or a method can be used as a callback, don't enclose
123
   it in a lambda. E.g. do 'do (callback)' rather than
Adrien Plazas's avatar
Adrien Plazas committed
124 125 126 127 128 129 130 131 132 133 134 135 136 137
   '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.

138
 * Any 'else', 'else if', 'catch' block or any other special block
Adrien Plazas's avatar
Adrien Plazas committed
139 140
   following another one should start in its own line and not on the
   same as the previous closing brace.
141 142

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

 * Append the original error message to the one you are building when
   refining an error.
Adrien Plazas's avatar
Adrien Plazas committed
147 148 149 150 151 152 153 154

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

 * 2 spaces for indentation.

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

155
 * Functions with no parameters should state it with the 'void' keyword.
Adrien Plazas's avatar
Adrien Plazas committed
156

157
 * In C files, function definitions are split into lines that way:
Adrien Plazas's avatar
Adrien Plazas committed
158 159 160 161 162 163 164
    * 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.

165
 * In header files, function definitions are split into lines that way:
Adrien Plazas's avatar
Adrien Plazas committed
166 167 168 169 170 171 172 173 174 175 176
    * 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)
177
   & shortening of names. E.g. discoverer over disco.
Adrien Plazas's avatar
Adrien Plazas committed
178

179
 * No single statement blocks.
Adrien Plazas's avatar
Adrien Plazas committed
180 181 182 183 184 185 186 187

 * 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
188
   to the class in it, in spinal-case. E.g. Games.GameSource class should
Adrien Plazas's avatar
Adrien Plazas committed
189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210
   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
211
   all be given as out arguments. In other words, prefer this:
Adrien Plazas's avatar
Adrien Plazas committed
212 213 214 215 216 217 218 219 220 221 222

   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.

223
 * Always add a comma after values of an array literal broken into
Adrien Plazas's avatar
Adrien Plazas committed
224 225 226 227 228 229 230 231
   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.