Ladies and gentleman, here's the 
       
    GTK-GNUTELLA CODING STYLE GUIDELINE
    $Id: STYLE,v 1.7 2004/01/01 13:25:29 rmanfredi Exp $

0. INTRODUCTION ********************************************************

    The purpose of this document is to describe the coding
    conventions used in gtk-gnutella in order to (try to) keep the
    code written by various gtk-gnutella contributors readable and
    the coding style consistent.

1. LINE FORMAT *********************************************************

1.1  Lines should have no more than 80 characters.

1.2  Tabs are set at 4 spaces. (in vi, :set ts=4)

1.3  Indentation is set to 4 spaces (in vi, :set sw=4).

1.4  Vi editor settings: the author has the following in his ~/.profile:

        export EXINIT="set ai ts=4 sw=4 sm nu shell=/usr/bin/ksh noflash"

2. COMMENTS ************************************************************

2.1  All functions must be consistently commented as:

        /*
         * function_name
         *
         * Purpose in life.
         * Returns blah blah.
         */
        void function_name(...args...)

2.2  Block comments must be formatted as:

        /*
         * This is a strategic comment
         */

    Strategic comments precede a set of lines of code and present what
    the following code does, why, etc...

2.3  "Tactical" comments appear at end of line:

        /* end-of-line comment for tactical comments */

    Tactical comments are meant to let the reader understand the code,
    and in particular the current line.  Avoid paraphrasing the code.

2.4  When commenting out a section of the code, don't use /* ... */ to avoid
     problems with /**/ comments already present in the code being commented
	 out.  Enclose the code within a #if 0 ... #endif section:

		#if 0
			/* This code is commented out */
			if (blah)
				foo;
		#endif

3. SPACES **************************************************************

3.1  No space should appear between a function and the parameters, that is:

      void f(args)    RIGHT
      void f (args)   WRONG

3.2  Operators should be surrounded by one space, that is:

      x = y     RIGHT
      x=y       WRONG

3.3  Put spaces between if and condition:

      if (cond)  RIGHT
      if(cond)   WRONG

      This applies to `while', `for' and `switch' as well.

3.4  There is no space in structure access operators:

        a->b    RIGHT
        c.f     RIGHT

        a -> b  WRONG
        c . f   WRONG

3.5  There is a single space AFTER a ",".

4. MISCELLANEOUS FORMATTING CONVENTIONS ********************************

4.1  Unnecessary parentheses should be avoided, for example:

        return expression       RIGHT
        return (expression) WRONG

4.2  strcmp() result:

        if (0 == strcmp(...))   RIGHT
        if (!strcmp(...))       WRONG

      Reason according to Raphael Manfredi:
      Although strictly equivalent, they don't read the same. The
      first represents an equality test, the second is a boolean
      negation. Since strcmp() returns a signed integer i.e., the
      difference between the first non-matching characters. The first
      form is much more readable. In contrast to the first, the latter
      form reads as: "if NOT strcmp [...]", i.e. "if this is not a
      string comparision [...]", which is clearly wrong. 

4.3  In general, explicitly tested returned values should appear first
     in the condition.  This is an extension of rule 4.2:

        if (-1 == read(fd, buf, len))   RIGHT
        if (read(fd, buf, len) == -1)   WRONG

	 This form emphasizes the relation of interest immediately, i.e.
     whether we're interested in "<", "=", or ">" comes first.

4.4  If the line is longer that 80 characters, it must be broken where
     you would normally insert a space.  The continuation line must be
     indented by 4 spaces.

        function_call(with, so_many, arguments, that, it_would_not,
            fit_on, a_single_line);

     The above can also be written as:

        function_call(
            with, so_many,
            arguments, that,
            it_would_not,
            fit_on, a_single_line);

4.5  When defining a function with a long argument list that does not
     fit on the 80-column line, it is important to have the opening '('
     in the argument list on the same line as the function name, or it
     will break the vi 'tags':

        static void function(
            unsigned char *argument1, int arg2)
        {
            /* Body */
        }

5. NAMING **************************************************************

5.1   Exported functions should be named after the package they appear
      in, for example, a package "foo" with header foo.h and
      implementation in foo.c:

        foo_init(void);
        foo_do_something(parameter);
        foo_close(void);

5.2  All functions are spelt lower-case, with _ to separate words.

5.3  Also every package should have a foo_init and foo_close
     function, even if they're empty. One day they won't be.

5.4  Short-lived variables (for example loop indices) should have a
     short name, for example "i" isn't bad. Conversely,
     long-lived variables must have a long, descriptive name, for
     example "queue_frozen" (if I tell you that this is a boolean
     value, you know what it means, don't you ?)

6. INDENTATION **********************************************************

6.1  Code should use classic K&R formatting, i.e. braces are put on the
     same line as the condition in tests, but on a line by itself for
     functions.  The closing brace aligns with the conditional, or with
     the opening brace for routines.

        if (c != b) {
            do_this();
            then_that();
        }

        void function(void)
        {
            ...
        }

6.2  You may omit the braces for one-line conditionals.

        if (a == b)
            do_this();

6.3  You may change the rules when it makes sense to.  For instance,
     the following unconventional indentation allows clear aligning of
     common things and makes the structure of the code clearer:

        if      (a == 1)    { ... }
        else if (b == 1)    { ... }
        else if (d >= a)    { ... }
        else                { ... }

6.4  Structures should be named, and formatted as conditionals, i.e.
     with the opening brace on the same line as the struct keyword:

        struct foo {
            int f_arg;      /* describe f_arg */
            int f_other;    /* describe f_other */
        };

7. OUTPUT ***************************************************************

7.1  Debugging output goes to stdout, that is

     if (dbg) {
        printf("Here's what's happening\n");
     }

8. MACROS ***************************************************************

8.1  Always protect an include file with an #ifndef/#endif block to avoid
     further interpretation of its content should the file be included
     more than once.  This prevents typedefs from being evaluated twice,
     and shuts compiler warning for possible macro redefinition:

        #ifndef _filename_h_
        #define _filename_h_
        ...
        include file definitions goes here.
        ...
        #endif /* _filename_h_ */

8.2  Always enclose macros that behave as statements within a do {} while (0)
     to make them real statements.  Leave the trailing ";" off, so that
     the invocation requires you to write it, thereby making the macro act
     as a regular function call, syntactically.

        #define DO_SEVERAL_THINGS() do {    \
            statement_1();                  \
            statement_2();                  \
        } while (0)

8.3  Always put () after a macro not taking any argument, to make it look
     like a function call as much as possible.

8.4  Macros that are meant for inlining short pieces of code should be
     spelt out in lowercase.  Macros that wish to stand out as a macro
     should be spelt out in uppercase.

9. MISCELLANEOUS ********************************************************

9.1  Use an empty "for (;;)" to start an infinite loop.

9.2  Use goto to factorize error cleanup code, since C lacks proper
     exception handling.  The goto label is "outdented" one level.

        if (-1 == write(fd, buf, len))
            goto error;

        ....

        return OK;

    error:
        close(fd);
        return ERROR;

9.3  Use the macro G_FREE_NULL() instead of g_free(). This macro sets the
     pointer to NULL after calling g_free(). Along with NULL-pointer checks,
     this prevents usage of deallocated memory and helps to trigger bugs.
