Ladies and gentleman, here's the 
       
    GTK-GNUTELLA CODING STYLE GUIDELINE

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:

        /*
         * 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.:
         *      51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 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 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  In comparisons constants and const-qualified variables are always
     to be put upfront. This avoids accidentally assigning a value by
     mistyping an operator (=, =!, >>=, <<=) making the expression an
     assignment instead of a mere comparison. Literal constants (123) have
     precedence over preprocessor constants (MAGIC) which have precedence over
     const-qualified variables (const int var). The operators > and <
     are exempt from this rule. By consisent use of this rule, readability
     is not affected.

        const struct blah;
        int var;
        [...]

        if (blah.member == var)    /* RIGHT */
        if (123 >= blah.member)    /* RIGHT */
        if (MAGIC != blah.member)  /* RIGHT */
        if (MAGIC != var)          /* RIGHT */
        if (123 <= var)            /* RIGHT */

      When making a "within range" test, it is however accepted to have
      the rule slightly relaxed, because it otherwise impacts readability
      too severely:

        if (x >= 0 && x <= 12)     /* ACCEPTABLE */

      For pointers checked for not being NULL, it is also acceptable
      to say:

        if (p != NULL)             /* ACCEPTABLE */

      The reason is that the obvious typo of inverting the operator to "=!"
      would be immediately caught by the compiler as assignment of an integer
      to a pointer without a cast.

      Furthermore, what should be really avoided is writing:

        if (p)                     /* AVOID */

      when "p" is a pointer because it does not highlight to the reader
      the true nature of the test and can mislead him into thinking the
      variable is a boolean.  In for() loops however, it is acceptable for
      more compact expressions provided it is obvious that the variable is a
      pointer (because it is assigned as a pointer or dereferenced):

        for (p = start; p; p = p->next)     /* ACCEPTABLE */

4.7   Useless boolean comparisons to constants must also be avoided:

        if (TRUE == value)  /* WRONG */
        if (value)          /* RIGHT */

        if (TRUE != value)  /* WRONG */
        if (!value)         /* RIGHT */


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 prefixed 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;
          ...
     }

9.5 When dereferencing a function pointer held in a structure, don't say:
    
        s->func(a, b)       # WRONG

    but rather:

        (*s->func)(a, b)    # RIGHT

    It emphasizes the fact that we're de-referencing a function pointer and
    it proctects against a possible

        #define func(a,b,c)

    somewhere, i.e. a 3-argument macro.  In the first case, cpp will cause
    a compilation error, whereas in the second case there will be no macro
    expansion.

/* vi: set tw=78 ts=4 sw=4 et: */
