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 - 2009 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 did some bugfixes.
-Library:
-- the interface was modified
-- new functions were added
+ 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:
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
--------------------------------------------------------------------------------
-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.
A brief overview for those that wish to work with the source.
-The Makefiles and configure script are generated by the autogen.sh script, usually
-only distributed with snapshot releases. Running autogen.sh requires automake
-and autoconf. GNU gettext may also be needed by autogen.sh.
+The Makefiles and configure script are generated by the autogen.sh script,
+usually only distributed with snapshot releases. Running autogen.sh requires
+automake and autoconf. GNU gettext may also be needed by autogen.sh.
-SVN commits _require_ an explicit log message. Think it will be used in the release
-Changelog.
+SVN commits _require_ an explicit log message. Think it will be used in the
+release Changelog.
Coders should respect general coding style (see CODING).
Coders, please resync po/POTFILES.in if you add or remove source files from src/
-directory (using regen_potfiles.sh script in po/) and re-run make update-po
-when appropriate to keep translations in sync with the code.
+directory (using regen_potfiles.sh script in po/) and re-run make update-po when
+appropriate to keep translations in sync with the code.
Maintainers, don't forget to run make update-po before releases.
Translators create a translation by creating the appropriate .po file in the /po
directory. Please see the gettext info pages for an overview and instructions.
Basically: Add your language code to the ALL_LINGUAS= line in configure.in,
-then get started translating the strings in your ??.po file.
-Note: The strings for debug output is intentionally not marked for translation.
+then get started translating the strings in your ??.po file. Note: The strings
+for debug output is intentionally not marked for translation.
-To update a specific translation, one may use make update-po PO=[lang] (ie. make update-po PO=fr).
-
-To update all translation files, use make update-po.
-You should only use it when needed (before a release or when there were many
-changes in source code).
+To update a specific translation, one may use make update-po PO=[lang] (ie.
+make update-po PO=fr).
+To update all translation files, use make update-po. You should only use it when
+needed (before a release or when there were many changes in source code).
Helper scripts:
projects / geeqie.git / commitdiff