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