1 # Coding and Documentation Style
3 [Error Logging](#error-logging)
4 [GPL header](#gpl-header)
5 [Git change log](#git-change-log)
7 [Software Tools](#software-tools)
8 [Documentation](#documentation)
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.
22 If the first word of the message is "error" or "warning" (case insensitive) the message will be color-coded appropriately.
24 - Note that these messages are output in the idle loop.
28 `print_term(gboolean err, const gchar *text_utf8)`
30 - If `err` is TRUE output is to STDERR, otherwise to STDOUT
32 ### DEBUG_NAME(widget)
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.
36 Sample command line call:
37 `GTK_DEBUG=interactive src/geeqie`
43 Include a header in every file, like this:
47 * Copyright (C) <year> The Geeqie Team
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.
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.
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.
67 * Optional description of purpose of file.
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.
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 "- ".
80 See also [A Note About Git Commit Messages](http://www.tpope.net/node/106)
87 There was the bug that something was wrong. I fixed it.
90 - the interface was modified
91 - new functions were added`
94 Also please use your full name and a working e-mail address as author for any contribution.
100 Indentation: tabs at 4 spaces
104 - of variables & functions: small\_letters
105 - of defines: CAPITAL\_LETTERS
107 Try to use explicit variable and function names.
108 Try not to use macros.
109 Use **either** "struct foo" OR "foo"; never both
127 if (<cond_very_very_very_very_very_very_very_very_very_long> &&
128 <cond2very_very_very_very_very_very_very_very_very_long>)
141 for (i = 0; i <= 10; i++)
152 gint bar(<var_def>, <var_def>, <var_def>)
158 return 0; // i.e. SUCCESS; if error, you must return minus <err_no> @FIXME
169 Pragma: (Indentation 2 spaces)
174 # define _(String) (String)
175 #endif /* ENABLE_NLS */
184 Use spaces around every operator (except `.`, `->`, `++` and `--`).
185 Unary operator `*` and `&` are missing the space from right, (and also unary `-`).
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.
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.
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:
204 astyle --options=<options file>
207 Where the options file might contain:
219 ### check-compiles.sh
221 This shell script is part of the Geeqie project and will compile Geeqie with various options.
225 A lint-style program may be used, e.g.
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>
231 Where the suppressions file might contain:
240 ### generate-man-page.sh
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.
247 ./scripts/generate-man-page.sh
252 Markdown documents may be validated with e.g. [markdownlint](https://github.com/markdownlint/markdownlint).
253 `mdl --style <style file>`
255 Where the style file might be:
259 rule 'MD009', :br_spaces => 2
260 rule 'MD010', :code_blocks => true
266 Shell scripts may also be validated, e.g.
269 shellcheck --enable=add-default-case,avoid-nullary-conditions,check-unassigned-uppercase,deprecate-which,quote-safe-variables
274 The .xml Help files may be validated with e.g. `xmllint`.
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.
283 To document the code use the following rules to allow extraction with Doxygen.
284 Not all comments have to be Doxygen comments.
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.
291 To document functions or big structures:
295 * @brief This is a short description of the function.
297 * This function does ...
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
308 To document members of a structure that have to be documented (use it at least
309 for big structures) use the `/**<` format:
312 gint counter; /**< This counter counts images */
316 Document TODO or FIXME comments as:
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).
333 The file `./scripts/doxygen-help.sh` may be used to integrate access to the Doxygen files into a code editor.
335 The following environment variables may be set to personalize the Doxygen output:
336 `DOCDIR=<output folder>`
337 `SRCDIR=<the folder above ./src>`
341 `INLINE_SOURCES=<YES|NO>`
342 `STRIP_CODE_COMMENTS=<YES|NO>`
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)
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`
354 But in case just think about that the documentation is for other developers not
355 for the end user. So keep the focus.