CODING.md

   1 # Coding and Documentation Style
   2
   3 [Error Logging](#error-logging)
   4 [GPL header](#gpl-header)
   5 [Git change log](#git-change-log)
   6 [Sources](#sources)
   7 [Software Tools](#software-tools)
   8 [Documentation](#documentation)
   9
  10 ---
  11
  12 ## Error Logging
  13
  14 ### DEBUG_0()
  15
  16 Use `DEBUG_0()` only for temporary debugging i.e. not in code in the repository.
  17 The user will then not see irrelevant debug output when the default
  18 `debug level = 0` is used.
  19
  20 ### log_printf()
  21
  22 If the first word of the message is "error" or "warning" (case insensitive) the message will be color-coded appropriately.
  23
  24 - Note that these messages are output in the idle loop.
  25
  26 ### print_term()
  27
  28 `print_term(gboolean err, const gchar *text_utf8)`
  29
  30 - If `err` is TRUE output is to STDERR, otherwise to STDOUT
  31
  32 ### DEBUG_NAME(widget)
  33
  34 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.
  35
  36 Sample command line call:
  37 `GTK_DEBUG=interactive src/geeqie`
  38
  39 ---
  40
  41 ## GPL header
  42
  43 Include a header in every file, like this:
  44
  45 ```c
  46 /*
  47  * Copyright (C) <year> The Geeqie Team
  48  *
  49  * Author: Author1
  50  * Author: Author2
  51  *
  52  * This program is free software; you can redistribute it and/or modify
  53  * it under the terms of the GNU General Public License as published by
  54  * the Free Software Foundation; either version 2 of the License, or
  55  * (at your option) any later version.
  56  *
  57  * This program is distributed in the hope that it will be useful,
  58  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  59  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  60  * GNU General Public License for more details.
  61  *
  62  * You should have received a copy of the GNU General Public License along
  63  * with this program; if not, write to the Free Software Foundation, Inc.,
  64  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  65  *
  66  *
  67  * Optional description of purpose of file.
  68  *
  69 */
  70 ```
  71
  72 ---
  73
  74 ## git change-log
  75
  76 If referencing a Geeqie GitHub issue, include the issue number in the summary line and a hyperlink to the GitHub issue webpage in the message body. Start with a short summary in the first line (without a dot at the end) followed by a empty line.
  77
  78 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 "- ".
  79
  80 See also [A Note About Git Commit Messages](http://www.tpope.net/node/106)
  81
  82 Example:
  83
  84 ```text
  85 I did some bugfixes
  86
  87 There was the bug that something was wrong. I fixed it.
  88
  89 Library:
  90 - the interface was modified
  91 - new functions were added`
  92 ```
  93
  94 Also please use your full name and a working e-mail address as author for any contribution.
  95
  96 ---
  97
  98 ## Sources
  99
 100 Indentation: tabs at 4 spaces
 101
 102 Names:
 103
 104 - of variables & functions: small\_letters
 105 - of defines: CAPITAL\_LETTERS
 106
 107 Try to use explicit variable and function names.
 108 Try not to use macros.
 109 Use **either** "struct foo" OR "foo"; never both
 110
 111 Conditions, cycles:
 112
 113 ```c
 114 if (<cond>)
 115         {
 116         <command>;
 117         ...
 118         <command>;
 119         }
 120 else
 121         {
 122         <command>;
 123         ...
 124         <command>;
 125         }
 126
 127 if (<cond_very_very_very_very_very_very_very_very_very_long> &&
 128 <cond2very_very_very_very_very_very_very_very_very_long>)
 129 <the_only_command>;
 130
 131 switch (<var>)
 132         {
 133         case 0:
 134                 <command>;
 135                 <command>;
 136                 break;
 137         case 1:
 138                 <command>; break;
 139         }
 140
 141 for (i = 0; i <= 10; i++)
 142         {
 143         <command>;
 144         ...
 145         <command>;
 146         }
 147 ```
 148
 149 Functions:
 150
 151 ```c
 152 gint bar(<var_def>, <var_def>, <var_def>)
 153 {
 154         <command>;
 155         ...
 156         <command>;
 157
 158         return 0; // i.e. SUCCESS; if error, you must return minus <err_no> @FIXME
 159 }
 160
 161 void bar2(void)
 162 {
 163         <command>;
 164         ...
 165         <command>;
 166 }
 167 ```
 168
 169 Pragma: (Indentation 2 spaces)
 170
 171 ```c
 172 #ifdef ENABLE_NLS
 173 #  undef _
 174 #  define _(String) (String)
 175 #endif /* ENABLE_NLS */
 176 ```
 177
 178 Headers:
 179
 180 ```c
 181 #ifndef _FILENAME_H
 182 ```
 183
 184 Use spaces around every operator (except `.`, `->`, `++` and `--`).
 185 Unary operator `*` and `&` are missing the space from right, (and also unary `-`).
 186
 187 As you can see above, parentheses are closed to inside, i.e. ` (blah blah) `
 188 In `function(<var>)` there is no space before the `(`.
 189 You *may* use more tabs/spaces than you *ought to* (according to this CodingStyle), if it makes your code nicer in being vertically indented.
 190 Variables declarations should be followed by a blank line and should always be at the start of the block.
 191
 192 Use glib types when possible (ie. gint and gchar instead of int and char).
 193 Use glib functions when possible (i.e. `g_ascii_isspace()` instead of `isspace()`).
 194 Check if used functions are not deprecated.
 195
 196 ---
 197 ## Software Tools
 198
 199 ### astyle
 200
 201 There is no code format program that exactly matches the above style, but if you are writing new code the following command line program formats code to a fairly close level:
 202
 203 ```sh
 204 astyle --options=<options file>
 205 ```
 206
 207 Where the options file might contain:
 208
 209 ```text
 210 style=vtk
 211 indent=force-tab
 212 pad-oper
 213 pad-header
 214 unpad-paren
 215 align-pointer=name
 216 align-reference=name
 217 ```
 218
 219 ### cppcheck
 220
 221 A lint-style program may be used, e.g.
 222
 223 ```sh
 224 cppcheck --language=c --library=gtk --enable=all --force  -USA_SIGINFO -UZD_EXPORT -Ugettext_noop -DG_KEY_FILE_DESKTOP_GROUP --template=gcc -I. --quiet --suppressions-list=<suppressions file>
 225 ```
 226
 227 Where the suppressions file might contain:
 228
 229 ```text
 230 missingIncludeSystem
 231 variableScope
 232 unusedFunction
 233 unmatchedSuppression
 234 ```
 235
 236 ### shellcheck
 237
 238 Shell scripts may also be validated, e.g.
 239
 240 ```sh
 241 shellcheck --enable=add-default-case,avoid-nullary-conditions,check-unassigned-uppercase,deprecate-which,quote-safe-variables
 242 ```
 243
 244 ### markdownlint
 245
 246 Markdown documents may be validated with e.g. [markdownlint](https://github.com/markdownlint/markdownlint).
 247 `mdl --style <style file>`
 248
 249 Where the style file might be:
 250
 251 ```text
 252 all
 253 rule 'MD009', :br_spaces => 2
 254 rule 'MD010', :code_blocks => true
 255 exclude_rule 'MD013'
 256 ```
 257
 258 ### xmllint
 259
 260 The .xml Help files may be validated with e.g. `xmllint`.
 261
 262 ### check-compiles.sh
 263
 264 This shell script is part of the Geeqie project and will compile Geeqie with various options.
 265
 266 ---
 267
 268 ## Documentation
 269
 270 Use American, rather than British English, spelling. This will facilitate consistent
 271 text searches. User text may be translated via the en_GB.po file.
 272
 273 To document the code use the following rules to allow extraction with Doxygen.
 274 Not all comments have to be Doxygen comments.
 275
 276 - Use C comments in plain C files and use C++ comments in C++ files for one line comments.
 277 - Use `/**` (note the two asterisks) to start comments to be extracted by Doxygen and start every following line with ` *` as shown below.
 278 - Use `@` to indicate Doxygen keywords/commands (see below).
 279 - Use the `@deprecated` command to indicate the function is subject to be deleted or to a  complete rewrite.
 280
 281 To document functions or big structures:
 282
 283 ```c
 284 /**
 285  * @brief This is a short description of the function.
 286  *
 287  * This function does ...
 288  *
 289  * @param x1 This is the first parameter named x1
 290  * @param y1 This is the second parameter named y1
 291  * @return What the function returns
 292  *    You can extend that return description (or anything else) by indenting the
 293  *    following lines until the next empty line or the next keyword/command.
 294  * @see Cross reference
 295  */
 296 ```
 297
 298 To document members of a structure that have to be documented (use it at least
 299 for big structures) use the `/**<` format:
 300
 301 ```c
 302 gint counter; /**< This counter counts images */
 303
 304 ```
 305
 306 Document TODO or FIXME comments as:
 307
 308 ```c
 309 /**
 310 * @todo
 311 ```
 312
 313 or
 314
 315 ```c
 316 /**
 317 * @FIXME
 318 ```
 319
 320 For further documentation about Doxygen see the [Doxygen Manual](https://www.doxygen.nl/index.html).
 321 For the possible commands you may use, see [Doxygen Special Commands](https://www.doxygen.nl/manual/commands.html).
 322
 323 The file `./scripts/doxygen-help.sh` may be used to integrate access to the Doxygen files into a code editor.
 324
 325 The following environment variables may be set to personalize the Doxygen output:
 326 `DOCDIR=<output folder>`
 327 `SRCDIR=<the folder above ./src>`
 328 `PROJECT=`
 329 `VERSION=`
 330 `PLANTUML_JAR_PATH=`
 331 `INLINE_SOURCES=<YES|NO>`
 332 `STRIP_CODE_COMMENTS=<YES|NO>`
 333
 334 Ref: [INLINE\_SOURCES](https://www.doxygen.nl/manual/config.html#cfg_inline_sources)
 335 Ref: [STRIP\_CODE\_COMMENTS](https://www.doxygen.nl/manual/config.html#cfg_strip_code_comments)
 336
 337 To include diagrams in the Doxygen output, the following are required to be installed. The installation process will vary between distributions:
 338 [The PlantUML jar](https://plantuml.com/download)
 339 `sudo apt install default-jre`
 340 `sudo apt install texlive-font-utils`
 341
 342 ---
 343
 344 But in case just think about that the documentation is for other developers not
 345 for the end user. So keep the focus.