CODING.md

   1 [Error Logging](#error-logging)
   2 [GPL header](#gpl-header)
   3 [Git change log](#git-change-log)
   4 [Sources](#sources)
   5 [Documentation](#documentation)
   6
   7 -----------
   8
   9
  10 # <a name='error-logging'>
  11 # Error Logging
  12
  13 `DEBUG_0()`
  14 Use `DEBUG_0()` only for temporary debugging i.e. not in code in the repository.
  15 The user will then not see irrelevant debug output when the default
  16 `debug level = 0` is used.
  17
  18 `log_printf()`
  19 If the first word of the message is "error" or "warning" (case insensitive) the message will be color-coded appropriately.
  20
  21  - Note that these messages are output in the idle loop.
  22
  23 `print_term(gboolean err, const gchar *text_utf8)`
  24
  25 - If `err` is TRUE output is to STDERR, otherwise to STDOUT
  26
  27
  28 `DEBUG_NAME(widget)`
  29 For use with the [GTKInspector](https://wiki.gnome.org/action/show/Projects/GTK/Inspector?action=show&redirect=Projects%2FGTK%2B%2FInspector) to provide a visual indication of where objects are declared.
  30
  31 Sample command line call:
  32 `GTK_DEBUG=interactive src/geeqie`
  33
  34 --------------------------------------------------------------------------------
  35
  36 # <a name='gpl-header'>
  37 # GPL header
  38
  39 Include a header in every file, like this:
  40
  41     /** @file
  42     * @brief Short description of this file.
  43     * @author Author1
  44     * @author Author2
  45     *
  46     * Optionally detailed description of this file
  47     * on more lines.
  48     */
  49
  50     /*
  51     *  This file is a part of Geeqie project (http://www.geeqie.org/).
  52     *  Copyright (C) 2008 - 2021 The Geeqie Team
  53     *
  54     *  This program is free software; you can redistribute it and/or modify it
  55     *  under the terms of the GNU General Public License as published by the Free
  56     *  Software Foundation; either version 2 of the License, or (at your option)
  57     *  any later version.
  58     *
  59     *  This program is distributed in the hope that it will be useful, but WITHOUT
  60     *  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  61     *  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  62     *  more details.
  63     */
  64
  65 -------------
  66
  67 # <a name='git-change-log'>
  68 # git change-log
  69
  70 If referencing a Geeqie GitHub issue, include the issue number in the summary line. Start with a short summary in the first line (without a dot at the end) followed by a empty line.
  71
  72 If referencing a Geeqie GitHub issue, include a hyperlink to the GitHub issue webpage in the message body. Use whole sentences beginning with Capital letter. For each modification use a new line. Or you can write the theme, colon and then every change on new line, begin with "- ".
  73
  74 See also [A Note About Git Commit Messages](http://www.tpope.net/node/106)
  75
  76 Example:
  77
  78    `I did some bugfixes`
  79
  80    `There was the bug that something was wrong. I fixed it.`
  81
  82   ` Library:`
  83    `- the interface was modified`
  84   `- new functions were added`
  85
  86 Also please use your full name and a working e-mail address as author for any contribution.
  87
  88 --------------------------------------------------------------------------------
  89
  90 # <a name='sources'>
  91 # Sources
  92
  93 Indentation: tabs at 4 spaces
  94
  95
  96 Names:
  97
  98 - of variables & functions:      small\_letters
  99 - of defines:            CAPITAL\_LETTERS
 100
 101 Try to use explicit variable and function names.
 102 Try not to use macros.
 103 Use EITHER "struct foo" OR "foo"; never both
 104
 105
 106 Conditions, cycles:
 107
 108     if (<cond>)
 109         {
 110         <command>;
 111         ...
 112         <command>;
 113         }
 114     else
 115         {
 116         <command>;
 117         ...
 118         <command>;
 119         }
 120
 121     if (<cond_very_very_very_very_very_very_very_very_very_long> &&
 122     <cond2very_very_very_very_very_very_very_very_very_long>)
 123     <the_only_command>;
 124
 125     switch (<var>)
 126         {
 127         case 0:
 128                 <command>;
 129                     <command>;
 130                     break;
 131         case 1:
 132                 <command>; break;
 133         }
 134
 135     for (i = 0; i <= 10; i++)
 136         {
 137         <command>;
 138         ...
 139         <command>;
 140         }
 141
 142 Functions:
 143
 144     gint bar(<var_def>, <var_def>, <var_def>)
 145     {
 146         <command>;
 147         ...
 148         <command>;
 149
 150         return 0; // i.e. SUCCESS; if error, you must return minus <err_no>
 151     }
 152
 153     void bar2(void)
 154     {
 155         <command>;
 156         ...
 157         <command>;
 158     }
 159
 160 Pragma: (Indentation 2 spaces)
 161
 162     #ifdef ENABLE_NLS
 163     #  undef _
 164     #  define _(String) (String)
 165     #endif /* ENABLE_NLS */
 166
 167 Headers:
 168
 169     #ifndef _FILENAME_H
 170
 171
 172 Use spaces around every operator (except ".", "->", "++" and "--").
 173 Unary operator '*' and '&' are missing the space from right, (and also unary '-').
 174
 175 As you can see above, parentheses are closed to inside, i.e. " (blah blah) "
 176 In "`function(<var>)`" there is no space before the '('.
 177 You MAY use more tabs/spaces than you OUGHT TO (according to this CodingStyle), if it makes your code nicer in being vertically indented.
 178 Variables declarations should be followed by a blank line and should always be at the start of the block.
 179
 180
 181 Use glib types when possible (ie. gint and gchar instead of int and char).
 182 Use glib functions when possible (ie. `g_ascii_isspace()` instead of `isspace()`).
 183 Check if used functions are not deprecated.
 184
 185 --------------------------------------------------------------------------------
 186
 187 # <a name='documentation'>
 188 # Documentation
 189
 190 Use American, rather than British English, spelling. This will facilitate consistent
 191 text searches. User text may be translated via the en_GB.po file.
 192
 193 To document the code use the following rules to allow extraction with doxygen.
 194 Do not save with comments. Not all comments have to be doxygen comments.
 195
 196 - Use C comments in plain C files and use C++ comments in C++ files for one line
 197   comments.
 198 - Use '/**' (note the two asterisks) to start comments to be extracted by
 199   doxygen and start every following line with " *".
 200 - Use '@' to indicate doxygen keywords/commands (see below).
 201 - Use the '@deprecated' command to tell if the function is subject to be deleted
 202   or to a  complete rewrite.
 203
 204 Example:
 205
 206 To document functions or big structures:
 207
 208     /**
 209      * @brief This is a short description of the function.
 210      *
 211      * This function does ...
 212      *
 213      * @param x1 This is the first parameter named x1
 214      * @param y1 This is the second parameter named y1
 215      * @return What the function returns
 216      *    You can extend that return description (or anything else) by indenting the
 217      *    following lines until the next empty line or the next keyword/command.
 218      * @see Cross reference
 219      */
 220
 221 To document members of a structure that have to be documented (use it at least
 222 for big structures) use the `/**<` format:
 223 `int counter; /**< This counter counts images */`
 224
 225 Document TODO or FIXME comments as:
 226
 227     /**
 228     * @todo
 229
 230 or
 231
 232     /**
 233     * @FIXME
 234
 235 For further documentation about doxygen see the [Doxygen Manual](https://www.doxygen.nl/index.html).
 236 For the possible commands you may use, see [Doxygen Special Commands](https://www.doxygen.nl/manual/commands.html).
 237
 238 The file `./scripts/doxygen-help.sh` may be used to integrate access to the Doxygen files into a code editor.
 239
 240 The following environment variables may be set to personalize the Doxygen output:
 241 `DOCDIR=<output folder>`
 242 `SRCDIR=<the folder above ./src>`
 243 `PROJECT=`
 244 `VERSION=`
 245 `PLANTUML_JAR_PATH=`
 246 `INLINE_SOURCES=<YES|NO>`
 247 `STRIP_CODE_COMMENTS=<YES|NO>`
 248
 249 Ref: [INLINE\_SOURCES](https://www.doxygen.nl/manual/config.html#cfg_inline_sources)
 250 Ref: [STRIP\_CODE\_COMMENTS](https://www.doxygen.nl/manual/config.html#cfg_strip_code_comments)
 251
 252 To include diagrams (if any) in the Doxygen output, the following are required to be installed. The installation process will vary between distributions:
 253 [The PlantUML jar](https://plantuml.com/download)
 254 `sudo apt install default-jre`
 255 `sudo apt install texlive-font-utils`
 256
 257 -------------
 258
 259 But in case just think about that the documentation is for other developers not
 260 for the end user. So keep the focus.