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