CODING.md

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