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