1 # Coding and Documentation Style
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 [Shell Script Style](#shell-script-style)
8 [External Software Tools](#external-software-tools)
9 [Geeqie Software Tools](#geeqie-software-tools)
10 [Documentation](#documentation)
11 [Documentation - C code](#c-code)
12 [Documentation - Script files](#script-files)
13 [Documentation - Markdown](#markdown)
22 Use `DEBUG_0()` only for temporary debugging i.e. not in code in the repository.
23 The user will then not see irrelevant debug output when the default
24 `debug level = 0` is used.
28 If the first word of the message is "error" or "warning" (case insensitive) the message will be color-coded appropriately.
30 - Note that these messages are output in the idle loop.
34 `print_term(gboolean err, const gchar *text_utf8)`
36 - If `err` is TRUE output is to STDERR, otherwise to STDOUT
38 ### DEBUG_NAME(widget)
40 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.
42 Sample command line call:
43 `GTK_DEBUG=interactive src/geeqie`
48 Use only for temporary debugging i.e. not in code in the repository
51 When the LogWindow has focus, the F1 key executes the following action as a command line program:
52 <options->log_window.action> <selected text>
53 The log_window.action value must be set by editing the geeqierc.xml file manually.
54 If no text is selected when the F1 key is pressed, the text either side of the cursor delimited by a space character or the beginning or end of the line is selected.
55 This feature may be used to open an editor at a file location listed in the backtrace.
60 Prints a dump of the FileData hash list as a ref. count followed by the full path of the item.
61 Use only for temporary debugging i.e. not in code in the repository
67 Include a header in every file, like this:
71 * Copyright (C) <year> The Geeqie Team
76 * This program is free software; you can redistribute it and/or modify
77 * it under the terms of the GNU General Public License as published by
78 * the Free Software Foundation; either version 2 of the License, or
79 * (at your option) any later version.
81 * This program is distributed in the hope that it will be useful,
82 * but WITHOUT ANY WARRANTY; without even the implied warranty of
83 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
84 * GNU General Public License for more details.
86 * You should have received a copy of the GNU General Public License along
87 * with this program; if not, write to the Free Software Foundation, Inc.,
88 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
91 * Optional description of purpose of file.
100 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.
102 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 "- ".
104 See also [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
111 There was the bug that something was wrong. I fixed it.
114 - the interface was modified
115 - new functions were added`
118 Also please use your full name and a working e-mail address as author for any contribution.
124 Indentation: tabs at 4 spaces
128 - of variables & functions: small\_letters
129 - of defines: CAPITAL\_LETTERS
131 Try to use explicit variable and function names.
132 Try not to use macros.
133 Use **either** "struct foo" OR "foo"; never both
151 if (<cond_very_very_very_very_very_very_very_very_very_long> &&
152 <cond2very_very_very_very_very_very_very_very_very_long>)
165 for (i = 0; i <= 10; i++)
176 gint bar(<var_def>, <var_def>, <var_def>)
182 return 0; // i.e. SUCCESS; if error, you must return minus <err_no> @FIXME
193 Pragma: (Indentation 2 spaces)
198 # define _(String) (String)
199 #endif /* ENABLE_NLS */
208 Use spaces around every operator (except `.`, `->`, `++` and `--`).
209 Unary operator `*` and `&` are missing the space from right, (and also unary `-`).
211 As you can see above, parentheses are closed to inside, i.e. ` (blah blah) `
212 In `function(<var>)` there is no space before the `(`.
213 You *may* use more tabs/spaces than you *ought to* (according to this CodingStyle), if it makes your code nicer in being vertically indented.
214 Variables declarations should be followed by a blank line and should always be at the start of the block.
216 Use glib types when possible (ie. gint and gchar instead of int and char).
217 Use glib functions when possible (i.e. `g_ascii_isspace()` instead of `isspace()`).
218 Check if used functions are not deprecated.
222 ## Shell Script Style
224 Use `/bin/sh` as the interpreter directive.
225 Ensure the script is POSIX compliant.
226 Use `printf` rather than `echo` except for plain text.
227 There are several versions of `mktemp`. Using the following definition helps portability (note that `template` is not optional):
230 mktemp [-d] [-q] template ...
233 and use for example this style:
236 mktemp "${TMPDIR:-/tmp}/geeqie.XXXXXXXXXX"
241 ## External Software Tools
245 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:
248 astyle --options=<options file>
251 Where the options file might contain:
265 A lint-style program may be used, e.g.
268 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>
271 Where the suppressions file might contain:
282 Markdown documents may be validated with e.g. [markdownlint](https://github.com/markdownlint/markdownlint).
285 mdl --style <style file>`
288 Where the style file might contain:
292 rule 'MD007', :indent => 4
293 rule 'MD009', :br_spaces => 2
294 rule 'MD010', :code_blocks => true
300 Shell scripts may also be validated, e.g.
303 shellcheck --enable=add-default-case,avoid-nullary-conditions,check-unassigned-uppercase,deprecate-which,quote-safe-variables
308 Shell scripts may formatted to some extent with [shfmt](https://github.com/mvdan/sh). At the time of writing it does not format `if`, `for` or `while` statements in the style used by Geeqie.
309 However the following script can be used to achieve that:
314 shfmt -s -p -ci -sr -fn | awk '
318 printf('%s\n', substr($0, 0, length($0) - 6));
319 printf('%s, substr("\t\t\t\t\t\t\t\t\t\t", 1, RLENGTH))
322 else if ($0 ~ /; do/)
325 printf('%s\n', substr($0, 0, length($0) - 4));
326 printf('%s', substr("\t\t\t\t\t\t\t\t\t\t", 1, RLENGTH))
338 The .xml Help files may be validated with e.g. `xmllint`.
342 ## Geeqie Software Tools
344 See the shell scripts section in the Doxygen documentation (`File List`, `detail level 3`, except the `src` sublist).
350 Use American, rather than British English, spelling. This will facilitate consistent
351 text searches. User text may be translated via the en_GB.po file.
353 To avoid confusion between American and British date formats, use ISO format (YYYY-MM-DD) where possible.
355 To document the code use the following rules to allow extraction with Doxygen.
356 Not all comments have to be Doxygen comments.
360 - Use C comments in plain C files and use C++ comments in C++ files for one line comments.
361 - Use `/**` (note the two asterisks) to start comments to be extracted by Doxygen and start every following line with ` *` as shown below.
362 - Use `@` to indicate Doxygen keywords/commands (see below).
363 - Use the `@deprecated` command to indicate the function is subject to be deleted or to a complete rewrite.
365 To document functions or big structures:
369 * @brief This is a short description of the function.
371 * This function does ...
373 * @param x1 This is the first parameter named x1
374 * @param y1 This is the second parameter named y1
375 * @return What the function returns
376 * You can extend that return description (or anything else) by indenting the
377 * following lines until the next empty line or the next keyword/command.
378 * @see Cross reference
382 To document members of a structure that have to be documented (use it at least
383 for big structures) use the `/**<` format:
386 gint counter; /**< This counter counts images */
390 Document TODO or FIXME comments as:
406 Script files such as .sh, .pl, and .awk should have the file relevant file extension or be symlinked as so.
408 Doxygen comments should start each line with `##`, and each file should contain:
412 ## @brief <one line description>
413 ## <contents description>
419 For a newline use two spaces (a backslash is not interpreted correctly by Doxygen).
423 For further documentation about Doxygen see the [Doxygen Manual](https://www.doxygen.nl/index.html).
424 For the possible commands you may use, see [Doxygen Special Commands](https://www.doxygen.nl/manual/commands.html).
426 The file `./scripts/doxygen-help.sh` may be used to integrate access to the Doxygen files into a code editor.
428 The following environment variables may be set to personalize the Doxygen output:
431 DOCDIR=<output folder>
432 SRCDIR=<the top level directory of the project>
436 INLINE_SOURCES=<YES|NO>
437 STRIP_CODE_COMMENTS=<YES|NO>
440 Ref: [INLINE\_SOURCES](https://www.doxygen.nl/manual/config.html#cfg_inline_sources)
441 Ref: [STRIP\_CODE\_COMMENTS](https://www.doxygen.nl/manual/config.html#cfg_strip_code_comments)
443 For shell scripts to be documented, the file `doxygen-bash.sed` must be in the `$PATH` environment variable.
444 It can be download from here:
447 wget https://raw.githubusercontent.com/Anvil/bash-doxygen/master/doxygen-bash.sed
448 chmod +x doxygen-bash.sed
451 To include diagrams in the Doxygen output, the following are required to be installed. The installation process will vary between distributions:
453 [The PlantUML jar](https://plantuml.com/download)
456 sudo apt install default-jre
457 sudo apt install texlive-font-utils
462 But in case just think about that the documentation is for other developers not
463 for the end user. So keep the focus.