Ladies and gentleman, here's the 
       
    GTK-GNUTELLA CODING STYLE GUIDELINE
    $Id: STYLE 10571 2006-03-14 20:52:52Z cbiere $

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"

1.5  Auto-setting tabstops in the file

        In Vi and compatibles (in first or last 5 lines of a file):
        /* vi: set ts=4 sw=4 cindent: */

        In emacs (in first 4 lines of a file):
        /* -*- mode: cc-mode; tab-width:4; -*- */
    
1.6  Indent command line options

     You can use indent with following options to help conform to the
     style guidelines:
     
        indent -i4 -ts4 -cdb -sc -br -ce -npcs -ci4 -cli0

1.7  Avoid unnecessary trailing whitespace at line endings.


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

2.1  Every file must start with a comment block like this:

        /*
         * $Id: STYLE 10571 2006-03-14 20:52:52Z cbiere $
         *
         * Copyright (c) [year], [name of the author]
         *
         *----------------------------------------------------------------------
         * This file is part of gtk-gnutella.
         *
         *  gtk-gnutella is free software; you can redistribute it and/or modify
         *  it under the terms of the GNU General Public License as published by
         *  the Free Software Foundation; either version 2 of the License, or
         *  (at your option) any later version.
         *
         *  gtk-gnutella is distributed in the hope that it will be useful,
         *  but WITHOUT ANY WARRANTY; without even the implied warranty of
         *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
         *  GNU General Public License for more details.
         *
         *  You should have received a copy of the GNU General Public License
         *  along with gtk-gnutella; if not, write to the Free Software
         *  Foundation, Inc.:
         *      59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
         *----------------------------------------------------------------------
         */

        /**
         * @ingroup [core, lib, gtk etc.]
         * @file
         *
         * [A headline that describes the file's function.]
         *
         * ([Detailed description of the file contents.])
         *
         * @author [name of the author (<e-mail address>)]
         * (@version [number])
         * @date [year]
         */

    The tag $Id: STYLE 10571 2006-03-14 20:52:52Z cbiere $ is expanded
    by SVN when the file is committed.

    The bracketed sections "[...]" have to be replaced by the respective
    things they describe. "(...)" sections are optional, also you can use
    proper speciall commands (@todo, @note, @warning etc.) in this block
    (see http://www.stack.nl/~dimitri/doxygen/commands.html for details).

    The text in the second comment section starting with "/**" contains the
    description of the file as it will show up in the API documentation
    generated by Doxygen. It is essential that the "@file" tag is in place
    as shown above and please fill [Detailed description ...] if possible.

    "@ingroup" is used for grouping at the generated documents, it will be
    added to the group or groups identified by the given group name (core,
    lib, etc.). See also doc/api/gtkg-apidoc.main, a group name is defined
    here.

    The following is an example from the actual source code:

        /**
         * @ingroup core
         * @file
         *
         * Bitzi Core search code.
         *
         * This code makes searches to the Bitzi (bitzi.com) meta-data
         * service. It is independent from any GUI functions and part
         * of the core of GTKG.
         *
         * @note
         * The code requires libxml to parse the XML responses.
         *
         * @author Alex Bennee <alex@bennee.com>
         * @date 2004
         */

    Don't forget to punctuate the headline and add a detailed description.

2.2  All functions must be consistently commented as:

        /**
         * Purpose in life.
         *
         * @param param1 blah blah
         * @param param2 blah blah
         *
         * @returns blah blah.
         */
        static struct type *
        function_name(...args...)

    When the API documentation is generated with Doxygen, the first
    sentence (up to the first ".") is treated as the short description
    of the function. The complete comment makes up the detailed
    description. It is welcome if additional tags like @param or
    @returns are used to further enhance the documentation. These 
    tags are documented in the manual of the Doxygen software package
    (see http://www.doxygen.org). The format is largely compatible to
    Javadoc. HTML tags should not be used.

    Since the function name does not appear in the leading comment, it
    is important to make it standout by moving it at the very beginning
    of the line, as shown in the example above.

2.2.1 A short comments at the same line can be commented as follows:

        ex. 1

        #define MACRO_NAME1 blah    /**< blah blah */
        #define MACRO_NAME2 blah    /**< blah blah */

        ex. 2

        struct name {
                struct type *name;  /**< blah blah */
                type *name;         /**< blah blah */
                type name;          /**< blah blah */
        };

    Due to the Doxygen's parsing method, if you forget to add "<" at the
    comment block (just "/**" there), from the above example, comment for
    the MACRO_NAME1 will be used for the MACRO_NAME2 or "type *name" will
    be commented by the comment for "struct type *name". Thus, you can
    assume the above examples are equivalent to:

        ex. 1

        /** blah blah */
        #define MACRO_NAME1 blah
        /** blah blah */
        #define MACRO_NAME2 blah

        ex. 2

        struct alive {
                /** blah blah */
                struct type *name;
                /** blah blah */
                type *name;
                /** blah blah */
                type name;

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

    (indent -cdb -sc)

2.4  "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.5  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

2.6  Don't use C++ style comments. True, they're valid in ISO C99 but some
     compilers don't support them.

    // Blah blah                WRONG
    /* Valuable comment */      RIGHT
    

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

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

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

      (indent -npcs)
      
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 ",".

3.6  There are no additional spaces in front of a `case' statement WRT to
     the `switch' statement:

     This one is WRONG:

        switch (cond) {
                case x: ...
                case y: ...
        }


     This one is RIGHT, the `case' statements are aligned with `switch':

        switch (cond) {
        case x: ...
        case y: ...
        }

    (indent -cli0)

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 comparison [...]", 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 than 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);

     (indent -ci4)
   
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 */
        }

4.6  When writing simple variable equality tests against a constant, do NOT
     put the constant at the head of the test.  This is different from
	 rules 4.2 and 4.3 in that those deal with potentially long function
	 calls, where it is best to highlight how we're going to use the
	 function's value.

		if (var == 4)	RIGHT
		if (4 == var)	WRONG

	 If the expression being tested is large, then it may be OK to
	 put the constant at the front.

		if (4 == (ax + by) / cz^wt)		OK

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.

9.4  If a function has unused parameters (e.g., a callback function) the
     names of the unused parameters should be appended with "unused_" and
     the function body should contain a (void) reference to it to document
     that it's intentionally unused and to suppress compiler warnings:

     int
     some_callback(int x, int unused_y)
     {
          (void) unused_y;
          ...
     }