[Xfce4-commits] <tumbler:master> Add coding style document.
Jannis Pohlmann
noreply at xfce.org
Sat Feb 19 22:34:01 CET 2011
Updating branch refs/heads/master
to 05c5dfbdb3131785131290fbb7e069c20a34ef57 (commit)
from 1bf98813ab4c33091b8a8280ef83c57c1354ebd0 (commit)
commit 05c5dfbdb3131785131290fbb7e069c20a34ef57
Author: Jannis Pohlmann <jannis at xfce.org>
Date: Sat Feb 19 22:33:18 2011 +0100
Add coding style document.
CODING_STYLE | 384 ++++++++++++++++++++++++++++++++++++++++++++
tumblerd/tumbler-service.c | 4 +-
2 files changed, 386 insertions(+), 2 deletions(-)
diff --git a/CODING_STYLE b/CODING_STYLE
new file mode 100644
index 0000000..53d8779
--- /dev/null
+++ b/CODING_STYLE
@@ -0,0 +1,384 @@
+Tumbler Coding Style
+====================
+
+This document intends to give information about the coding style to be
+used when contributing code to tumbler. It does not claim to be
+complete. Parts of it are taken or inspired from the Clutter coding
+style document.
+
+An example of a good coding style (from the perspective of this
+document) is tumblerd/tumbler-service.c. In the following, the most
+important requirements for writing consistent code for tumbler are
+explained.
+
+
+Line Width
+==========
+
+The maximum line width for source files is 90 characters. This limit may
+be exceeded when there is no way around it. Accepted ways to wrap long
+lines caused by function calls are
+
+ result = some_function_with_a_very_long_name (first_parameter,
+ second_parameter,
+ third_parameter);
+
+and
+
+ long_result_variable =
+ some_function_with_a_very_long_name (first_parameter,
+ second_parameter,
+ third_parameter);
+
+where the result variable name is too long to fit the function call
+into the 90 characters limit even when wrapping the parameters.
+
+Do not separate the function name from its arguments like this:
+
+ /* bad */
+ some_function_with_a_long_name
+ (long_argument_name1, long_argument_name2);
+
+Instead, consider using shorter variable names as aliases:
+
+ /* good */
+ short1 = long_argument_name1;
+ short2 = long_argument_name2;
+ some_function_with_a_long_name (short1, short2);
+
+The line width limit of 90 characters does not apply to header files.
+However the alignment and parameter indentation rules explained in the
+section "Functions and Braces" still apply to header files.
+
+
+Whitespace
+==========
+
+Always insert a space before a parenthesis but never after or
+between the opening or closing parenthesis and a parameter.
+
+ /* good */
+ if (condition)
+ foo (argument1, argument2);
+
+ /* bad */
+ if(condition)
+ foo(argument1, argument2);
+
+ /* bad */
+ if ( condition )
+ foo ( argument1, argument 2 );
+
+
+Indentation and Braces
+======================
+
+Use spaces only, tabs are not allowed. The indentation for each level is
+2 spaces in addition to the previous level. Braces add another level of
+indentation. Valid indentations and uses of braces are:
+
+Single-line statements:
+
+ /* good */
+ if (condition)
+ single_line_statement ();
+
+Multiple statements:
+
+ /* good */
+ if (condition)
+ {
+ a_statement ();
+ another_statement ();
+ }
+
+Multiple and single statements:
+
+ /* good */
+ if (condition)
+ {
+ a_statement ();
+ another_statement ();
+ }
+ else
+ {
+ one_more_statement ();
+ }
+
+Do and while loops:
+
+ /* good */
+ while (foo)
+ {
+ bar ();
+ }
+
+ /* good */
+ do
+ {
+ bar ();
+ }
+ while (foo);
+
+Switch statements:
+
+ /* good */
+ switch (condition)
+ {
+ case FOO:
+ do_something ();
+ break;
+ case BAR:
+ do_something_else ();
+ break;
+ default:
+ do_whatever_you_need_to_do ();
+ break;
+ }
+
+ /* bad */
+ switch (condition) {
+ case FOO:
+ do_something ();
+ break;
+ }
+
+ /* bad */
+ switch (condition)
+ {
+ case FOO:
+ do_something ();
+ break;
+ }
+
+ /* bad */
+ switch (condition)
+ {
+ case FOO: do_something ();
+ break;
+ }
+
+ /* bad */
+ switch (condition)
+ {
+ case FOO:
+ do_something ();
+ break;
+ }
+
+Nested if statements:
+
+ /* good */
+ if (condition)
+ {
+ /* here the same rules as on the top level apply again */
+ if (another_condition)
+ single_statement ();
+ else if (yet_another_condition)
+ another_single_statement ();
+ }
+
+Do not put curly braces into the same line as the condition:
+
+ /* bad */
+ if (condition) {
+ ...
+ }
+
+Do not asymmetrically use and not use braces:
+
+ /* bad */
+ if (condition)
+ {
+ /* multiple statements */
+ }
+ else
+ single_statement ();
+
+If there are multiple conditions in a single if statement spread across
+more than one line, always use curly braces:
+
+ /* good */
+ if (condition1
+ && condition2)
+ {
+ /* multiple or single statement(s) */
+ }
+
+
+Functions and Braces
+====================
+
+Braces in function definitions are not indented. Parameters are to be
+wrapped and aligned so that the end results looks like this:
+
+Function declarations:
+
+ /* good */
+ static gchar *some_type_your_function (SomeType *object,
+ int another parameter,
+ gchar **and_another_one);
+ static gboolean some_type_some_longer_function_name (SomeType *object);
+
+Function definitions:
+
+ /* good */
+ static gchar *
+ some_type_your_function (SomeType *object,
+ int another_parameter,
+ gchar **and_another_one)
+ {
+ /* declarations */
+ /* assertions */
+ /* actual code */
+ }
+
+Do not declare functions like this:
+
+ /* bad */
+ static gchar *some_type_your_function (SomeType *object,
+ int another parameter,
+ gchar **and_another_one);
+ static gboolean some_type_some_longer_function_name (SomeType *object);
+
+Or like this:
+
+ /* bad */
+ static gchar *some_type_your_function (SomeType *object, int another parameter, gchar **and_another_one);
+ static gboolean some_type_some_longer_function_name (SomeType *object);
+
+
+Empty Lines
+===========
+
+Between declarations of groups of structs, enums, functions, static
+variables and macros there have to be three empty lines to make the
+different items easier to spot and distinguish. There also have to be
+three empty lines between function definitions.
+
+Also, when declaring data structures, use newlines to separate logical
+sections of member variables:
+
+ struct _TumblerService
+ {
+ /* thumbnailers and preferred thumbnailers */
+ GHashTable *thumbnailers;
+ GHashTable *preferred_thumbnailers;
+
+ /* cached supported URIs and MIME types */
+ gchar **mime_types;
+ gchar **uri_schemes;
+
+ /* protection against threads */
+ GMutex *mutex;
+ };
+
+
+Variable Declarations
+=====================
+
+Variables may only be declared at the top of a function. Variable
+declarations in blocks (code surrounded by braces) are not allowed.
+
+Declarations follow special alignment and sorting rules. The sorting
+order of declarations is determined by:
+
+ 1. number of characters of the variable type
+ 2. ascending alphabetical order of the type (case-insensitive)
+ 3. ascending alphabetical order of the variable name
+
+Here is an example of how a variable declaration sequence has to
+look like:
+
+ TumblerSpecializedThumbnailer *thumbnailer;
+ const gchar * const *mime_types;
+ const gchar *static_name;
+ gboolean result = FALSE;
+ GFile *file;
+ gchar *dynamic_name;
+ guint index;
+ guint n;
+
+
+Assertions
+==========
+
+In order to make it easier to detect broken code paths, assertions in
+the form of g_return_if_fail() and g_return_val_if_fail() statements are
+used in almost all methods. When implementing new methods in your code,
+please make sure to check the input parameters for type incompatiblities
+or memory corruption.
+
+
+More on Conditions
+==================
+
+Do not check boolean values for equality like this:
+
+ /* bad */
+ if (condition == TRUE)
+ ...
+
+Instead, just do it like this:
+
+ /* good */
+ if (condition)
+ ...
+
+Be explicit when checking pointers however:
+
+ /* good */
+ if (some_pointer == NULL)
+ ...
+
+ /* good */
+ if (some_pointer != NULL)
+ ...
+
+Do not simply do it like this:
+
+ /* bad */
+ if (some_pointer)
+ ...
+
+If you have so many conditions in an if statement that you need to split
+them up into multiple lines, the logical operatiors should always be
+placed at the beginning of the line, like this:
+
+ /* good */
+ if (condtion1
+ || condition 2
+ || condition 3)
+ {
+ ...
+ }
+
+Don't place the logical operators at the end of the line:
+
+ /* bad */
+ if (condition1 ||
+ condition2 ||
+ conidition3)
+ {
+ ...
+ }
+
+
+Header Files
+============
+
+Header files should always include the following code in addition to the
+license header (example for tumbler-data-structure.h):
+
+ #ifndef __TUMBLER_DATA_STRUCTURE_H__
+ #define __TUMBLER_DATA_STRUCTURE_H__
+
+ #include <something-that-also-includes-glib-object.h>
+
+ G_BEGIN_DECLS
+
+ ...
+
+ G_END_DECLS
+
+ #endif /* !__TUMBLER_DATA_STRUCTURE_H__ */
diff --git a/tumblerd/tumbler-service.c b/tumblerd/tumbler-service.c
index d00a477..92ab7ac 100644
--- a/tumblerd/tumbler-service.c
+++ b/tumblerd/tumbler-service.c
@@ -279,8 +279,8 @@ tumbler_service_remove_scheduler (TumblerScheduler *scheduler,
static void
tumbler_service_constructed (GObject *object)
{
- TumblerService *service = TUMBLER_SERVICE (object);
TumblerScheduler *scheduler;
+ TumblerService *service = TUMBLER_SERVICE (object);
/* chain up to parent classes */
if (G_OBJECT_CLASS (tumbler_service_parent_class)->constructed != NULL)
@@ -941,8 +941,8 @@ void
tumbler_service_get_supported (TumblerService *service,
DBusGMethodInvocation *context)
{
- const gchar *const *uri_schemes;
const gchar *const *mime_types;
+ const gchar *const *uri_schemes;
dbus_async_return_if_fail (TUMBLER_IS_SERVICE (service), context);
More information about the Xfce4-commits
mailing list