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