GPL header, in every file, like this:
-/** @file relativ/path/with/this/file/name.c
- * Short description of this file.
- * @author Author1
- * @author Author2
+/** \file
+ * \short Short description of this file.
+ * \author Author1
+ * \author Author2
*
* Optionaly detailed description of this file
* on more lines.
*/
-
+
/*
- * This file is a part of Geeqie project (http://geeqie.sourceforge.net/).
- * Copyright (C) 2008 Geeqie team
+ * This file is a part of Geeqie project (http://www.geeqie.org/).
+ * Copyright (C) 2008 - 2016 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 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.
+ * 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.
*/
--------------------------------------------------------------------------------
svn change-log:
-Use whole sentences begins with Capital letter. For each modification use new line.
-Or you can write the theme, colon and then every change on new line, begin
-with "- ".
+Start with a short summary in the first line (without a dot at the end) followed
+by a empty line. Use whole sentences begins with Capital letter. For each
+modification use new line. Or you can write the theme, colon and then every
+change on new line, begin with "- ".
+
+See also: http://www.tpope.net/node/106
Example:
-I done some bugfixes.
-Library:
-- I change the interface
-- added some new functions
+ I did some bugfixes
+
+ There was the bug that something was wrong. I fixed it.
+
+ Library:
+ - the interface was modified
+ - new functions were added
--------------------------------------------------------------------------------
sources:
Indentation: tabs
-Names of variables & functions: small_letters
- of defines: CAPITAL_LETTERS
+Names 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
+
Conditions, cycles:
if (<cond>)
...
<command>;
}
-
+
if (<cond_very_very_very_very_very_very_very_very_very_long> &&
- <cond2very_very_very_very_very_very_very_very_very_long)
+ <cond2very_very_very_very_very_very_very_very_very_long>)
<the_only_command>;
switch (<var>)
...
<command>;
}
-
+
Functions:
-int bar(<var_def>, <var_def>, <var_def>)
+gint bar(<var_def>, <var_def>, <var_def>)
{
<command>;
...
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(<var>)" there are no space before '('.
+ In "function(<var>)" there are no space before '('.
You MAY use more tabs/spaces than you OUGHT TO (according to this CodingStyle), if
it makes your code nicer in being verticaly indented.
+Variables declarations should be followed by a blank line and should always be
+at the start of the block.
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
-Documentation: use Doxygen
+Documentation:
+
+To document the code use the following rules to allow extraction with doxygen.
+Do not save with comments. Not all comments have to be doxygen comments.
+
+- Use C comments in plain C files and use C++ comments in C++ files for one line
+ comments.
+- Use '/**' (note the two asterisks) to start comments to be extracted by
+ doxygen and start every following line with " *".
+- Use '\' to indicate doxygen keywords/commands (see below).
+- Use the '\deprecated' command to tell if the function is subject to be deleted
+ or to a complete rewrite.
+
+Example:
+
+To document functions or big structures:
+ /**
+ * \brief This is a short description of the function.
+ *
+ * This function does ...
+ *
+ * \param x1 This is the first parameter named x1
+ * \param y1 This is the second parameter named y1
+ * \return What the function returns
+ * You can extend that return description (or anything else) by indenting the
+ * following lines until the next empty line or the next keyword/command.
+ * \see Cross reference
+ */
+
+To document members of a structure that have to be documented (use it at least
+for big structures) use the '/**<' format:
+ int counter; /**< This counter counts images */
+
+For further documentation about doxygen see
+http://www.stack.nl/~dimitri/doxygen/manual.html. For the possible commands you
+can use see http://www.stack.nl/~dimitri/doxygen/commands.html.
+
+But in case just think about that the documentation is for other developers not
+for the end user. So keep the focus.