X-Git-Url: http://geeqie.org/cgi-bin/gitweb.cgi?p=geeqie.git;a=blobdiff_plain;f=CODING;h=2db81115f0170b555db953ff79a7131c93815d3a;hp=42bcb382f879c8a899f8b20e1aea5faa6ae165ff;hb=686b5bed543c5abd0310eff74d3d8083ab1ff01c;hpb=0fb3e0276867a5224e267571b04641290d9b1013 diff --git a/CODING b/CODING index 42bcb382..2db81115 100644 --- a/CODING +++ b/CODING @@ -1,38 +1,186 @@ -Please keep the general coding style of Geeqie: +GPL header, in every file, like this: -Space after if, while and for: +/** \file + * \short Short description of this file. + * \author Author1 + * \author Author2 + * + * Optionaly detailed description of this file + * on more lines. + */ -while (...) -for (...) -if (...) +/* + * This file is a part of Geeqie project (http://geeqie.sourceforge.net/). + * Copyright (C) 2008 - 2012 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. + */ -Indentation of {}: +-------------------------------------------------------------------------------- -while (...) +svn change-log: + +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 + + 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 + +Try to use explicit variable and function names. + +Try not to use macros. +Use EITHER "struct foo" OR "foo"; never both + + +Conditions, cycles: + +if () { + ; ... + ; } - -if (...) +else { + ; ... + ; } -else + +if ( && + ) + ; + +switch () + { + case 0: + ; + ; + break; + case 1: + ; break; + } + +for (i = 0; i <= 10; i++) { + ; ... + ; } -Spaces around operators: -i = 2; +Functions: + +gint bar(, , ) +{ + ; + ... + ; + + return 0; // i.e. SUCCESS; if error, you must return minus +} + +void bar2(void) +{ + ; + ... + ; +} + +Pragma: (Indentation 2 spaces) + +#ifdef ENABLE_NLS +# undef _ +# define _(String) (String) +#endif /* ENABLE_NLS */ + +Headers: -Space after comma: -func(a, b, c); +#ifndef _FILENAME_H +-------------------------------------------------------------------------------- + +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 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. + +-------------------------------------------------------------------------------- + +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()). -Please use glib types when possible (ie. gint and gchar instead of int and char) -. +Check if used functions are not deprecated. + +-------------------------------------------------------------------------------- + +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 */ -Check twice the indentation and spurious whitespaces. +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. -Try to use explicit variable and function names +But in case just think about that the documentation is for other developers not +for the end user. So keep the focus.