annotate CODING @ 737:8a8873e7a552

Make shell command and its option rc file options instead of hardcoded strings. This allows users to modify the shell command that execute "editors". Two new options appear in rc file: - shell.path (default to "/bin/sh") - shell.options (default to "-c") These options can only be changed from the rc file, not at runtime. Tests are made to check that shell.path is not empty and lead to an executable file.

GPL header, in every file, like this:

/** @file relativ/path/with/this/file/name.c
 * 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 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:

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 "- ".

Example:

I done some bugfixes.
Library:
- I change the interface
- added some new functions

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

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:

int 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.

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

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: use Doxygen