annotate CODING @ 1805:fccac8fde6c0

Little macro correction

GPL header, in every file, like this:

/** \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 - 2010 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.
 */

--------------------------------------------------------------------------------

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 (<cond>)
	{
	<command>;
	...
	<command>;
	}
else
	{
	<command>;
	...
	<command>;
	}

if (<cond_very_very_very_very_very_very_very_very_very_long> &&
    <cond2very_very_very_very_very_very_very_very_very_long>)
    <the_only_command>;

switch (<var>)
	{
	case 0:
		<command>;
		<command>;
		break;
	case 1:
		<command>; break;
	}

for (i = 0; i <= 10; i++)
	{
	<command>;
	...
	<command>;
	}


Functions:

gint bar(<var_def>, <var_def>, <var_def>)
{
	<command>;
	...
	<command>;

	return 0; // i.e. SUCCESS; if error, you must return minus <err_no>
}

void bar2(void)
{
	<command>;
	...
	<command>;
}

Pragma: (Indentation 2 spaces)

#ifdef ENABLE_NLS
#  undef _
#  define _(String) (String)
#endif /* ENABLE_NLS */

Headers:

#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(<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.

--------------------------------------------------------------------------------

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.

--------------------------------------------------------------------------------

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.