From 31197b3d4f2ee55c84a2ae5c71995e2c5dad91c8 Mon Sep 17 00:00:00 2001 From: Colin Clark Date: Sun, 7 Nov 2021 16:35:13 +0000 Subject: [PATCH] Update coding documentation Include section on tools which might be used to check sources in CODING.md, plus reformatting of file. Include check-compiles.sh script. --- CODING.md | 391 +++++++++++++++++++++++--------------- scripts/check-compiles.sh | 76 ++++++++ 2 files changed, 314 insertions(+), 153 deletions(-) create mode 100755 scripts/check-compiles.sh diff --git a/CODING.md b/CODING.md index 7a517e91..9e6bec02 100644 --- a/CODING.md +++ b/CODING.md @@ -1,238 +1,323 @@ +# Coding and Documentation Style + [Error Logging](#error-logging) [GPL header](#gpl-header) [Git change log](#git-change-log) [Sources](#sources) +[Software Tools](#software-tools) [Documentation](#documentation) ------------ +--- +## Error Logging -# -# Error Logging +### 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. +- 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` --------------------------------------------------------------------------------- +--- -# -# GPL header +## 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 "- ". +```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](http://www.tpope.net/node/106) 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 +## Sources 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 + { + ; + ... + ; + } + +if ( && +) +; + +switch () + { + case 0: + ; + ; + break; + case 1: + ; break; + } + +for (i = 0; i <= 10; i++) + { + ; + ... + ; + } +``` Functions: - gint bar(, , ) - { - ; - ... - ; +```c +gint bar(, , ) +{ + ; + ... + ; - return 0; // i.e. SUCCESS; if error, you must return minus - } + return 0; // i.e. SUCCESS; if error, you must return minus @FIXME +} - void bar2(void) - { - ; - ... - ; - } +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 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 (ie. `g_ascii_isspace()` instead of `isspace()`). +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. --------------------------------------------------------------------------------- +--- +## 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 + +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= +``` + +Where the suppressions file might contain: + +```text +missingIncludeSystem +variableScope +unusedFunction +unmatchedSuppression +``` + +### shellcheck -# -# Documentation +Shell scripts may also be validated, e.g. + +```sh +shellcheck --enable=add-default-case,avoid-nullary-conditions,check-unassigned-uppercase,deprecate-which,quote-safe-variables +``` + +### markdownlint + +Markdown documents may be validated with e.g. [markdownlint](https://github.com/markdownlint/markdownlint). +`mdl --style