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