CODING

   1 GPL header, in every file, like this:
   2
   3 /** \file
   4  * \short Short description of this file.
   5  * \author Author1
   6  * \author Author2
   7  *
   8  * Optionaly detailed description of this file
   9  * on more lines.
  10  */
  11
  12 /*
  13  *  This file is a part of Geeqie project (http://geeqie.sourceforge.net/).
  14  *  Copyright (C) 2008 - 2012 The Geeqie Team
  15  *
  16  *  This program is free software; you can redistribute it and/or modify it
  17  *  under the terms of the GNU General Public License as published by the Free
  18  *  Software Foundation; either version 2 of the License, or (at your option)
  19  *  any later version.
  20  *
  21  *  This program is distributed in the hope that it will be useful, but WITHOUT
  22  *  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  23  *  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  24  *  more details.
  25  */
  26
  27 --------------------------------------------------------------------------------
  28
  29 svn change-log:
  30
  31 Start with a short summary in the first line (without a dot at the end) followed
  32 by a empty line. Use whole sentences begins with Capital letter. For each
  33 modification use new line. Or you can write the theme, colon and then every
  34 change on new line, begin with "- ".
  35
  36 See also: http://www.tpope.net/node/106
  37
  38 Example:
  39
  40    I did some bugfixes
  41
  42    There was the bug that something was wrong. I fixed it.
  43
  44    Library:
  45    - the interface was modified
  46    - new functions were added
  47
  48 --------------------------------------------------------------------------------
  49
  50 sources:
  51
  52 Indentation: tabs
  53 Names of variables & functions:  small_letters
  54       of defines:                CAPITAL_LETTERS
  55
  56 Try to use explicit variable and function names.
  57
  58 Try not to use macros.
  59 Use EITHER "struct foo" OR "foo"; never both
  60
  61
  62 Conditions, cycles:
  63
  64 if (<cond>)
  65         {
  66         <command>;
  67         ...
  68         <command>;
  69         }
  70 else
  71         {
  72         <command>;
  73         ...
  74         <command>;
  75         }
  76
  77 if (<cond_very_very_very_very_very_very_very_very_very_long> &&
  78     <cond2very_very_very_very_very_very_very_very_very_long>)
  79     <the_only_command>;
  80
  81 switch (<var>)
  82         {
  83         case 0:
  84                 <command>;
  85                 <command>;
  86                 break;
  87         case 1:
  88                 <command>; break;
  89         }
  90
  91 for (i = 0; i <= 10; i++)
  92         {
  93         <command>;
  94         ...
  95         <command>;
  96         }
  97
  98
  99 Functions:
 100
 101 gint bar(<var_def>, <var_def>, <var_def>)
 102 {
 103         <command>;
 104         ...
 105         <command>;
 106
 107         return 0; // i.e. SUCCESS; if error, you must return minus <err_no>
 108 }
 109
 110 void bar2(void)
 111 {
 112         <command>;
 113         ...
 114         <command>;
 115 }
 116
 117 Pragma: (Indentation 2 spaces)
 118
 119 #ifdef ENABLE_NLS
 120 #  undef _
 121 #  define _(String) (String)
 122 #endif /* ENABLE_NLS */
 123
 124 Headers:
 125
 126 #ifndef _FILENAME_H
 127
 128 --------------------------------------------------------------------------------
 129
 130 Use spaces around every operator (except ".", "->", "++" and "--");
 131         unary operator '*' and '&' are missing the space from right;
 132         (and also unary '-').
 133 As you can see above, parentheses are closed to inside, i.e. " (blah blah) "
 134     In "function(<var>)" there are no space before '('.
 135 You MAY use more tabs/spaces than you OUGHT TO (according to this CodingStyle), if
 136         it makes your code nicer in being verticaly indented.
 137 Variables declarations should be followed by a blank line and should always be
 138 at the start of the block.
 139
 140 --------------------------------------------------------------------------------
 141
 142 Use glib types when possible (ie. gint and gchar instead of int and char).
 143 Use glib functions when possible (ie. g_ascii_isspace() instead of isspace()).
 144 Check if used functions are not deprecated.
 145
 146 --------------------------------------------------------------------------------
 147
 148 Documentation:
 149
 150 To document the code use the following rules to allow extraction with doxygen.
 151 Do not save with comments. Not all comments have to be doxygen comments.
 152
 153 - Use C comments in plain C files and use C++ comments in C++ files for one line
 154   comments.
 155 - Use '/**' (note the two asterisks) to start comments to be extracted by
 156   doxygen and start every following line with " *".
 157 - Use '\' to indicate doxygen keywords/commands (see below).
 158 - Use the '\deprecated' command to tell if the function is subject to be deleted
 159   or to a  complete rewrite.
 160
 161 Example:
 162
 163 To document functions or big structures:
 164    /**
 165     * \brief This is a short description of the function.
 166     *
 167     * This function does ...
 168     *
 169     * \param x1 This is the first parameter named x1
 170     * \param y1 This is the second parameter named y1
 171     * \return What the function returns
 172     *    You can extend that return description (or anything else) by indenting the
 173     *    following lines until the next empty line or the next keyword/command.
 174     * \see Cross reference
 175     */
 176
 177 To document members of a structure that have to be documented (use it at least
 178 for big structures) use the '/**<' format:
 179    int counter; /**< This counter counts images */
 180
 181 For further documentation about doxygen see
 182 http://www.stack.nl/~dimitri/doxygen/manual.html. For the possible commands you
 183 can use see http://www.stack.nl/~dimitri/doxygen/commands.html.
 184
 185 But in case just think about that the documentation is for other developers not
 186 for the end user. So keep the focus.