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 --------------------------------------------------------------------------------
  67
  68 sources:
  69
  70 Indentation: tabs
  71 Names of variables & functions:  small_letters
  72       of defines:                CAPITAL_LETTERS
  73
  74 Try to use explicit variable and function names.
  75
  76 Try not to use macros.
  77 Use EITHER "struct foo" OR "foo"; never both
  78
  79
  80 Conditions, cycles:
  81
  82 if (<cond>)
  83         {
  84         <command>;
  85         ...
  86         <command>;
  87         }
  88 else
  89         {
  90         <command>;
  91         ...
  92         <command>;
  93         }
  94
  95 if (<cond_very_very_very_very_very_very_very_very_very_long> &&
  96     <cond2very_very_very_very_very_very_very_very_very_long>)
  97     <the_only_command>;
  98
  99 switch (<var>)
 100         {
 101         case 0:
 102                 <command>;
 103                 <command>;
 104                 break;
 105         case 1:
 106                 <command>; break;
 107         }
 108
 109 for (i = 0; i <= 10; i++)
 110         {
 111         <command>;
 112         ...
 113         <command>;
 114         }
 115
 116
 117 Functions:
 118
 119 gint bar(<var_def>, <var_def>, <var_def>)
 120 {
 121         <command>;
 122         ...
 123         <command>;
 124
 125         return 0; // i.e. SUCCESS; if error, you must return minus <err_no>
 126 }
 127
 128 void bar2(void)
 129 {
 130         <command>;
 131         ...
 132         <command>;
 133 }
 134
 135 Pragma: (Indentation 2 spaces)
 136
 137 #ifdef ENABLE_NLS
 138 #  undef _
 139 #  define _(String) (String)
 140 #endif /* ENABLE_NLS */
 141
 142 Headers:
 143
 144 #ifndef _FILENAME_H
 145
 146 --------------------------------------------------------------------------------
 147
 148 Use spaces around every operator (except ".", "->", "++" and "--");
 149         unary operator '*' and '&' are missing the space from right;
 150         (and also unary '-').
 151 As you can see above, parentheses are closed to inside, i.e. " (blah blah) "
 152     In "function(<var>)" there are no space before '('.
 153 You MAY use more tabs/spaces than you OUGHT TO (according to this CodingStyle), if
 154         it makes your code nicer in being verticaly indented.
 155 Variables declarations should be followed by a blank line and should always be
 156 at the start of the block.
 157
 158 --------------------------------------------------------------------------------
 159
 160 Use glib types when possible (ie. gint and gchar instead of int and char).
 161 Use glib functions when possible (ie. g_ascii_isspace() instead of isspace()).
 162 Check if used functions are not deprecated.
 163
 164 --------------------------------------------------------------------------------
 165
 166 Documentation:
 167
 168 To document the code use the following rules to allow extraction with doxygen.
 169 Do not save with comments. Not all comments have to be doxygen comments.
 170
 171 - Use C comments in plain C files and use C++ comments in C++ files for one line
 172   comments.
 173 - Use '/**' (note the two asterisks) to start comments to be extracted by
 174   doxygen and start every following line with " *".
 175 - Use '\' to indicate doxygen keywords/commands (see below).
 176 - Use the '\deprecated' command to tell if the function is subject to be deleted
 177   or to a  complete rewrite.
 178
 179 Example:
 180
 181 To document functions or big structures:
 182    /**
 183     * \brief This is a short description of the function.
 184     *
 185     * This function does ...
 186     *
 187     * \param x1 This is the first parameter named x1
 188     * \param y1 This is the second parameter named y1
 189     * \return What the function returns
 190     *    You can extend that return description (or anything else) by indenting the
 191     *    following lines until the next empty line or the next keyword/command.
 192     * \see Cross reference
 193     */
 194
 195 To document members of a structure that have to be documented (use it at least
 196 for big structures) use the '/**<' format:
 197    int counter; /**< This counter counts images */
 198
 199 For further documentation about doxygen see
 200 http://www.stack.nl/~dimitri/doxygen/manual.html. For the possible commands you
 201 can use see http://www.stack.nl/~dimitri/doxygen/commands.html.
 202
 203 But in case just think about that the documentation is for other developers not
 204 for the end user. So keep the focus.