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 ### check-compiles.sh
 220
 221 This shell script is part of the Geeqie project and will compile Geeqie with various options.
 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 ### generate-man-page.sh
 241
 242 This script is part of the Geeqie project and should be used to generate the Geeqie man page from Geeqie's command line
 243 help output and also update the Command Line Options section of the Help files.
 244 The programs help2man and doclifter are required - both are available as .deb packages.
 245
 246 ```sh
 247 ./scripts/generate-man-page.sh
 248 ```
 249
 250 ### markdownlint
 251
 252 Markdown documents may be validated with e.g. [markdownlint](https://github.com/markdownlint/markdownlint).
 253 `mdl --style <style file>`
 254
 255 Where the style file might be:
 256
 257 ```text
 258 all
 259 rule 'MD009', :br_spaces => 2
 260 rule 'MD010', :code_blocks => true
 261 exclude_rule 'MD013'
 262 ```
 263
 264 ### shellcheck
 265
 266 Shell scripts may also be validated, e.g.
 267
 268 ```sh
 269 shellcheck --enable=add-default-case,avoid-nullary-conditions,check-unassigned-uppercase,deprecate-which,quote-safe-variables
 270 ```
 271
 272 ### xmllint
 273
 274 The .xml Help files may be validated with e.g. `xmllint`.
 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 - Use C comments in plain C files and use C++ comments in C++ files for one line comments.
 287 - Use `/**` (note the two asterisks) to start comments to be extracted by Doxygen and start every following line with ` *` as shown below.
 288 - Use `@` to indicate Doxygen keywords/commands (see below).
 289 - Use the `@deprecated` command to indicate the function is subject to be deleted or to a  complete rewrite.
 290
 291 To document functions or big structures:
 292
 293 ```c
 294 /**
 295  * @brief This is a short description of the function.
 296  *
 297  * This function does ...
 298  *
 299  * @param x1 This is the first parameter named x1
 300  * @param y1 This is the second parameter named y1
 301  * @return What the function returns
 302  *    You can extend that return description (or anything else) by indenting the
 303  *    following lines until the next empty line or the next keyword/command.
 304  * @see Cross reference
 305  */
 306 ```
 307
 308 To document members of a structure that have to be documented (use it at least
 309 for big structures) use the `/**<` format:
 310
 311 ```c
 312 gint counter; /**< This counter counts images */
 313
 314 ```
 315
 316 Document TODO or FIXME comments as:
 317
 318 ```c
 319 /**
 320 * @todo
 321 ```
 322
 323 or
 324
 325 ```c
 326 /**
 327 * @FIXME
 328 ```
 329
 330 For further documentation about Doxygen see the [Doxygen Manual](https://www.doxygen.nl/index.html).
 331 For the possible commands you may use, see [Doxygen Special Commands](https://www.doxygen.nl/manual/commands.html).
 332
 333 The file `./scripts/doxygen-help.sh` may be used to integrate access to the Doxygen files into a code editor.
 334
 335 The following environment variables may be set to personalize the Doxygen output:
 336 `DOCDIR=<output folder>`
 337 `SRCDIR=<the folder above ./src>`
 338 `PROJECT=`
 339 `VERSION=`
 340 `PLANTUML_JAR_PATH=`
 341 `INLINE_SOURCES=<YES|NO>`
 342 `STRIP_CODE_COMMENTS=<YES|NO>`
 343
 344 Ref: [INLINE\_SOURCES](https://www.doxygen.nl/manual/config.html#cfg_inline_sources)
 345 Ref: [STRIP\_CODE\_COMMENTS](https://www.doxygen.nl/manual/config.html#cfg_strip_code_comments)
 346
 347 To include diagrams in the Doxygen output, the following are required to be installed. The installation process will vary between distributions:
 348 [The PlantUML jar](https://plantuml.com/download)
 349 `sudo apt install default-jre`
 350 `sudo apt install texlive-font-utils`
 351
 352 ---
 353
 354 But in case just think about that the documentation is for other developers not
 355 for the end user. So keep the focus.