annotate CODING @ 1811:f405ec9b696b default tip

Some small logic mistakes Use boolean operators for booleans and bitwise otherwise only.
author mow
date Mon, 10 May 2010 11:33:13 +0000
parents 956aab097ea7
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
1 GPL header, in every file, like this:
524
7659ccaf2a74 Document the Geeqie coding style.
zas_
parents:
diff changeset
2
1645
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
3 /** \file
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
4 * \short Short description of this file.
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
5 * \author Author1
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
6 * \author Author2
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
7 *
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
8 * Optionaly detailed description of this file
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
9 * on more lines.
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
10 */
1645
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
11
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
12 /*
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
13 * This file is a part of Geeqie project (http://geeqie.sourceforge.net/).
1802
956aab097ea7 added 2010 to copyright text
nadvornik
parents: 1645
diff changeset
14 * Copyright (C) 2008 - 2010 The Geeqie Team
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
15 *
1645
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
16 * This program is free software; you can redistribute it and/or modify it
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
17 * under the terms of the GNU General Public License as published by the Free
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
18 * Software Foundation; either version 2 of the License, or (at your option)
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
19 * any later version.
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
20 *
1645
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
21 * This program is distributed in the hope that it will be useful, but WITHOUT
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
22 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
23 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
24 * more details.
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
25 */
524
7659ccaf2a74 Document the Geeqie coding style.
zas_
parents:
diff changeset
26
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
27 --------------------------------------------------------------------------------
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
28
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
29 svn change-log:
524
7659ccaf2a74 Document the Geeqie coding style.
zas_
parents:
diff changeset
30
1645
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
31 Start with a short summary in the first line (without a dot at the end) followed
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
32 by a empty line. Use whole sentences begins with Capital letter. For each
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
33 modification use new line. Or you can write the theme, colon and then every
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
34 change on new line, begin with "- ".
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
35
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
36 See also: http://www.tpope.net/node/106
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
37
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
38 Example:
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
39
1645
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
40 I did some bugfixes
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
41
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
42 There was the bug that something was wrong. I fixed it.
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
43
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
44 Library:
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
45 - the interface was modified
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
46 - new functions were added
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
47
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
48 --------------------------------------------------------------------------------
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
49
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
50 sources:
524
7659ccaf2a74 Document the Geeqie coding style.
zas_
parents:
diff changeset
51
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
52 Indentation: tabs
1645
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
53 Names of variables & functions: small_letters
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
54 of defines: CAPITAL_LETTERS
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
55
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
56 Try to use explicit variable and function names.
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
57
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
58 Try not to use macros.
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
59 Use EITHER "struct foo" OR "foo"; never both
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
60
1645
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
61
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
62 Conditions, cycles:
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
63
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
64 if (<cond>)
524
7659ccaf2a74 Document the Geeqie coding style.
zas_
parents:
diff changeset
65 {
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
66 <command>;
524
7659ccaf2a74 Document the Geeqie coding style.
zas_
parents:
diff changeset
67 ...
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
68 <command>;
524
7659ccaf2a74 Document the Geeqie coding style.
zas_
parents:
diff changeset
69 }
7659ccaf2a74 Document the Geeqie coding style.
zas_
parents:
diff changeset
70 else
7659ccaf2a74 Document the Geeqie coding style.
zas_
parents:
diff changeset
71 {
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
72 <command>;
524
7659ccaf2a74 Document the Geeqie coding style.
zas_
parents:
diff changeset
73 ...
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
74 <command>;
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
75 }
1645
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
76
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
77 if (<cond_very_very_very_very_very_very_very_very_very_long> &&
1645
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
78 <cond2very_very_very_very_very_very_very_very_very_long>)
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
79 <the_only_command>;
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
80
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
81 switch (<var>)
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
82 {
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
83 case 0:
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
84 <command>;
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
85 <command>;
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
86 break;
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
87 case 1:
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
88 <command>; break;
524
7659ccaf2a74 Document the Geeqie coding style.
zas_
parents:
diff changeset
89 }
7659ccaf2a74 Document the Geeqie coding style.
zas_
parents:
diff changeset
90
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
91 for (i = 0; i <= 10; i++)
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
92 {
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
93 <command>;
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
94 ...
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
95 <command>;
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
96 }
1645
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
97
524
7659ccaf2a74 Document the Geeqie coding style.
zas_
parents:
diff changeset
98
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
99 Functions:
524
7659ccaf2a74 Document the Geeqie coding style.
zas_
parents:
diff changeset
100
809
83d3abd80b64 Minor fixes and add a note about variable declaration.
zas_
parents: 685
diff changeset
101 gint bar(<var_def>, <var_def>, <var_def>)
611
f31ae0d9e163 Update CODING and HACKING files, and add po/README file for translators.
zas_
parents: 525
diff changeset
102 {
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
103 <command>;
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
104 ...
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
105 <command>;
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
106
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
107 return 0; // i.e. SUCCESS; if error, you must return minus <err_no>
611
f31ae0d9e163 Update CODING and HACKING files, and add po/README file for translators.
zas_
parents: 525
diff changeset
108 }
f31ae0d9e163 Update CODING and HACKING files, and add po/README file for translators.
zas_
parents: 525
diff changeset
109
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
110 void bar2(void)
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
111 {
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
112 <command>;
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
113 ...
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
114 <command>;
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
115 }
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
116
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
117 Pragma: (Indentation 2 spaces)
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
118
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
119 #ifdef ENABLE_NLS
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
120 # undef _
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
121 # define _(String) (String)
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
122 #endif /* ENABLE_NLS */
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
123
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
124 Headers:
524
7659ccaf2a74 Document the Geeqie coding style.
zas_
parents:
diff changeset
125
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
126 #ifndef _FILENAME_H
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
127
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
128 --------------------------------------------------------------------------------
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
129
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
130 Use spaces around every operator (except ".", "->", "++" and "--");
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
131 unary operator '*' and '&' are missing the space from right;
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
132 (and also unary '-').
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
133 As you can see above, parentheses are closed to inside, i.e. " (blah blah) "
1645
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
134 In "function(<var>)" there are no space before '('.
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
135 You MAY use more tabs/spaces than you OUGHT TO (according to this CodingStyle), if
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
136 it makes your code nicer in being verticaly indented.
809
83d3abd80b64 Minor fixes and add a note about variable declaration.
zas_
parents: 685
diff changeset
137 Variables declarations should be followed by a blank line and should always be
83d3abd80b64 Minor fixes and add a note about variable declaration.
zas_
parents: 685
diff changeset
138 at the start of the block.
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
139
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
140 --------------------------------------------------------------------------------
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
141
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
142 Use glib types when possible (ie. gint and gchar instead of int and char).
611
f31ae0d9e163 Update CODING and HACKING files, and add po/README file for translators.
zas_
parents: 525
diff changeset
143 Use glib functions when possible (ie. g_ascii_isspace() instead of isspace()).
f31ae0d9e163 Update CODING and HACKING files, and add po/README file for translators.
zas_
parents: 525
diff changeset
144 Check if used functions are not deprecated.
f31ae0d9e163 Update CODING and HACKING files, and add po/README file for translators.
zas_
parents: 525
diff changeset
145
685
f20e7cebcb12 Updated CODING (GPL header, macros, svn change-log, ...).
bruclik
parents: 611
diff changeset
146 --------------------------------------------------------------------------------
524
7659ccaf2a74 Document the Geeqie coding style.
zas_
parents:
diff changeset
147
1645
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
148 Documentation:
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
149
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
150 To document the code use the following rules to allow extraction with doxygen.
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
151 Do not save with comments. Not all comments have to be doxygen comments.
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
152
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
153 - Use C comments in plain C files and use C++ comments in C++ files for one line
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
154 comments.
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
155 - Use '/**' (note the two asterisks) to start comments to be extracted by
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
156 doxygen and start every following line with " *".
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
157 - Use '\' to indicate doxygen keywords/commands (see below).
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
158 - Use the '\deprecated' command to tell if the function is subject to be deleted
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
159 or to a complete rewrite.
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
160
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
161 Example:
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
162
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
163 To document functions or big structures:
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
164 /**
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
165 * \brief This is a short description of the function.
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
166 *
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
167 * This function does ...
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
168 *
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
169 * \param x1 This is the first parameter named x1
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
170 * \param y1 This is the second parameter named y1
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
171 * \return What the function returns
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
172 * You can extend that return description (or anything else) by indenting the
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
173 * following lines until the next empty line or the next keyword/command.
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
174 * \see Cross reference
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
175 */
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
176
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
177 To document members of a structure that have to be documented (use it at least
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
178 for big structures) use the '/**<' format:
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
179 int counter; /**< This counter counts images */
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
180
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
181 For further documentation about doxygen see
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
182 http://www.stack.nl/~dimitri/doxygen/manual.html. For the possible commands you
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
183 can use see http://www.stack.nl/~dimitri/doxygen/commands.html.
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
184
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
185 But in case just think about that the documentation is for other developers not
b9a9a457860d Update documentation
mow
parents: 1284
diff changeset
186 for the end user. So keep the focus.