X-Git-Url: http://geeqie.org/cgi-bin/gitweb.cgi?p=geeqie.git;a=blobdiff_plain;f=CODING.md;h=7a517e91f504e431b320632d781808ac608ce431;hp=2e57b8c800e5cc16fe24f2c49aa1b64e2ef3ee72;hb=refs%2Fheads%2Fmaster;hpb=7a0e70421c6096eebfc2e821d0bccef3d70e12f0
diff --git a/CODING.md b/CODING.md
index 2e57b8c8..4f4d492f 100644
--- a/CODING.md
+++ b/CODING.md
@@ -1,254 +1,463 @@
-[Log Window](#log-window)
+# Coding and Documentation Style
+
+[Error Logging](#error-logging)
[GPL header](#gpl-header)
[Git change log](#git-change-log)
-[Sources](#sources)
+[Source Code Style](#source-code-style)
+[Shell Script Style](#shell-script-style)
+[External Software Tools](#external-software-tools)
+[Geeqie Software Tools](#geeqie-software-tools)
[Documentation](#documentation)
+[Documentation - C code](#c-code)
+[Documentation - Script files](#script-files)
+[Documentation - Markdown](#markdown)
+[Doxygen](#doxygen)
------------
+---
+## Error Logging
-#
-# Log Window
+### DEBUG_0()
-`DEBUG_0()`
Use `DEBUG_0()` only for temporary debugging i.e. not in code in the repository.
The user will then not see irrelevant debug output when the default
`debug level = 0` is used.
-`log_printf()`
+### log_printf()
+
If the first word of the message is "error" or "warning" (case insensitive) the message will be color-coded appropriately.
+- Note that these messages are output in the idle loop.
+
+### print_term()
+
+`print_term(gboolean err, const gchar *text_utf8)`
+
+- If `err` is TRUE output is to STDERR, otherwise to STDOUT
+
+### DEBUG_NAME(widget)
-`DEBUG_NAME(widget)`
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.
Sample command line call:
`GTK_DEBUG=interactive src/geeqie`
---------------------------------------------------------------------------------
+### DEBUG_BT()
+
+Prints a backtrace.
+Use only for temporary debugging i.e. not in code in the repository
+
+### DEBUG_FD()
+
+Prints a dump of the FileData hash list as a ref. count followed by the full path of the item.
+Use only for temporary debugging i.e. not in code in the repository
+
+### Log Window
-#
-# GPL header
+When the Log Window has focus, the F1 key executes the action specified in `Edit/Preferences/Behavior/Log Window F1 Command` with the selected text as a parameter.
+If no text is selected, the entire line is passed to the command.
+This feature may be used to open an editor at a file location in the text string.
+
+---
+
+## GPL header
Include a header in every file, like this:
- /** @file
- * @brief Short description of this file.
- * @author Author1
- * @author Author2
- *
- * Optionally detailed description of this file
- * on more lines.
- */
-
- /*
- * This file is a part of Geeqie project (http://www.geeqie.org/).
- * Copyright (C) 2008 - 2021 The Geeqie Team
- *
- * This program is free software; you can redistribute it and/or modify it
- * under the terms of the GNU General Public License as published by the Free
- * Software Foundation; either version 2 of the License, or (at your option)
- * any later version.
- *
- * This program is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
- * more details.
- */
-
--------------
-
-#
-# git change-log
-
-If referencing a Geeqie GitHub issue, include the issue number in the summary line. Start with a short summary in the first line (without a dot at the end) followed by a empty line.
-
-If referencing a Geeqie GitHub issue, include a hyperlink to the GitHub issue webpage in the message body. 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 "- ".
-
-See also [A Note About Git Commit Messages](http://www.tpope.net/node/106)
+```c
+/*
+ * Copyright (C) The Geeqie Team
+ *
+ * Author: Author1
+ * Author: Author2
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ *
+ * Optional description of purpose of file.
+ *
+*/
+```
+
+---
+
+## git change-log
+
+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.
+
+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 "- ".
+
+See also [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
Example:
- `I did some bugfixes`
+```text
+I did some bugfixes
- `There was the bug that something was wrong. I fixed it.`
+There was the bug that something was wrong. I fixed it.
- ` Library:`
- `- the interface was modified`
- `- new functions were added`
+Library:
+- the interface was modified
+- new functions were added`
+```
Also please use your full name and a working e-mail address as author for any contribution.
---------------------------------------------------------------------------------
+---
-#
-# Sources
+## Source Code Style
Indentation: tabs at 4 spaces
-
-
+
Names:
-- of variables & functions: small\_letters
-- of defines: CAPITAL\_LETTERS
+- of variables & functions: small\_letters
+- of defines: CAPITAL\_LETTERS
Try to use explicit variable and function names.
Try not to use macros.
-Use EITHER "struct foo" OR "foo"; never both
-
+Use **either** "struct foo" OR "foo"; never both
Conditions, cycles:
- if ()
- {
- ;
- ...
- ;
- }
- else
- {
- ;
- ...
- ;
- }
-
- if ( &&
- )
- ;
-
- switch ()
- {
- case 0:
- ;
- ;
- break;
- case 1:
- ; break;
- }
-
- for (i = 0; i <= 10; i++)
- {
- ;
- ...
- ;
- }
+```c
+if ()
+ {
+ ;
+ ...
+ ;
+ }
+else
+ {
+ ;
+ ...
+ ;
+ }
-Functions:
+if ( &&
+)
+;
- gint bar(, , )
+switch ()
{
- ;
- ...
- ;
-
- return 0; // i.e. SUCCESS; if error, you must return minus
+ case 0:
+ ;
+ ;
+ break;
+ case 1:
+ ; break;
}
- void bar2(void)
+for (i = 0; i <= 10; i++)
{
- ;
- ...
- ;
+ ;
+ ...
+ ;
}
+```
+
+Functions:
+
+```c
+gint bar(, , )
+{
+ ;
+ ...
+ ;
+
+ return 0; // i.e. SUCCESS; if error, you must return minus @FIXME
+}
+
+void bar2(void)
+{
+ ;
+ ...
+ ;
+}
+```
Pragma: (Indentation 2 spaces)
- #ifdef ENABLE_NLS
- # undef _
- # define _(String) (String)
- #endif /* ENABLE_NLS */
+```c
+#ifdef ENABLE_NLS
+# undef _
+# define _(String) (String)
+#endif /* ENABLE_NLS */
+```
Headers:
- #ifndef _FILENAME_H
+```c
+#ifndef _FILENAME_H
+```
+Use [Names and Order of Includes](https://google.github.io/styleguide/cppguide.html#Names_and_Order_of_Includes) for headers include order.
-Use spaces around every operator (except ".", "->", "++" and "--").
-Unary operator '*' and '&' are missing the space from right, (and also unary '-').
+Use spaces around every operator (except `.`, `->`, `++` and `--`).
+Unary operator `*` and `&` are missing the space from right, (and also unary `-`).
-As you can see above, parentheses are closed to inside, i.e. " (blah blah) "
-In "`function()`" there is no space before the '('.
-You MAY use more tabs/spaces than you OUGHT TO (according to this CodingStyle), if it makes your code nicer in being vertically indented.
+As you can see above, parentheses are closed to inside, i.e. ` (blah blah) `
+In `function()` there is no space before the `(`.
+You *may* use more tabs/spaces than you *ought to* (according to this CodingStyle), if it makes your code nicer in being vertically indented.
Variables declarations should be followed by a blank line and should always be at the start of the block.
+Use glib types when possible (ie. gint and gchar instead of int and char).
+Use glib functions when possible (i.e. `g_ascii_isspace()` instead of `isspace()`).
+Check if used functions are not deprecated.
+
+---
+
+## Shell Script Style
+
+Use `/bin/sh` as the interpreter directive.
+Ensure the script is POSIX compliant.
+Use `printf` rather than `echo` except for plain text.
+There are several versions of `mktemp`. Using the following definition helps portability (note that `template` is not optional):
+
+```sh
+mktemp [-d] [-q] template ...
+```
+
+and use for example this style:
+
+```sh
+mktemp "${TMPDIR:-/tmp}/geeqie.XXXXXXXXXX"
+```
+
+---
+
+## External Software Tools
+
+### astyle
+
+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:
+
+```sh
+astyle --options=
+```
+
+Where the options file might contain:
+
+```text
+style=vtk
+indent=force-tab
+pad-oper
+pad-header
+unpad-paren
+align-pointer=name
+align-reference=name
+```
+
+### cppcheck
-Use glib types when possible (ie. gint and gchar instead of int and char).
-Use glib functions when possible (ie. `g_ascii_isspace()` instead of `isspace()`).
-Check if used functions are not deprecated.
+A lint-style program may be used, e.g.
---------------------------------------------------------------------------------
+```sh
+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=
+```
-#
-# Documentation
+Where the suppressions file might contain:
+
+```text
+missingIncludeSystem
+variableScope
+unusedFunction
+unmatchedSuppression
+```
+
+### markdownlint
+
+Markdown documents may be validated with e.g. [markdownlint](https://github.com/markdownlint/markdownlint).
+
+```sh
+mdl --style