CODING

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