1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
Formatting
==========
All code should follow the same formatting standards which are broadly based on the GNU style (http://www.gnu.org/prep/standards.html) with some
additions. Briefly:
- Tab indents are used and braces for blocks go on the same line as the block statement:
if (x < foo (y, z)) {
haha = bar[4] + 5;
} else {
while (z) {
haha += foo (z, z);
z--;
}
return abc (haha);
}
Braces should be omitted for single-line blocks, but included for all blocks in a multi-part if statement which has blocks containing more than
one line (as above).
- Spaces should be present between function name and argument block, and after commas:
foo (z, z)
- In pointer types, the '*' is grouped with the variable name, not with the base type.
int *a;
Not:
int* a;
In cases where there is no variable name, for instance, return values, there should be a single space between the base type and the '*'.
Type casts should have no space between the type and '*', but a space before the variable being cast:
(gchar*) foobar;
(gchar**) &foobar;
- Function and variable names are lower_case_with_underscores, type names are CamelCase and macro names are UPPER_CASE_WITH_UNDERSCORES.
- Comparisons to NULL, TRUE and FALSE should always be made explicit, for clarity.
- Code should be wrapped at the 150th column, such that it doesn't require horizontal scrolling on a decent-sized display.
Don't wrap at the 80th column.
Documentation comments
======================
All public API functions should have inline documentation headers in the gtk-doc style. For more information about gtk-doc comments, see the gtk-doc
manual (http://library.gnome.org/devel/gtk-doc-manual/stable/). There are a few conventions above and beyond the standard gtk-doc formatting which
libgdata employs:
- For API which returns allocated memory, the relevant free/unref function must be mentioned in the "Return value" part of the documentation:
* Return value: a new #GDataEntry; unref with g_object_unref()
If the function can also return NULL (on error, for example) or some other "default" value (-1, 0, etc.), format it as follows:
* Return value: a new #GDataGDFeedLink, or %NULL; free with gdata_gd_feed_link_free()
Note that if a function returns NULL as a result of a precondition or assertion failure, this should not be listed in the documentation. The
precondition itself may be listed in the function documentation prose, but if it's the only reason for a function to return NULL, the "or %NULL"
clause should be omitted.
- When adding API, make sure to add a "Since" clause:
* Since: 0.2.0
- For object methods, the "self" parameter should be documented simply as "a #GObjectType":
* @self: a #GDataQuery
- For function parameters which can legitimately be set to NULL (or some other default value), list that as follows:
* @updated_max: the new maximum update time, or %NULL
- If numbers, such as -1, are mentioned in documentation as values to be passed around in code, they should be wrapped in a DocBook "code" tag
(e.g. "<code class="literal">-1</code>"), so that they appear similarly to NULL in the documentation.
- The documentation explaining the purpose of a property, its limitations, interpretation, etc., should be given in the gtk-doc comment for the
GObject property itself, not in the documentation for its getter or setter. The documentation for the getter and setter should be stubs which
refer to the property's documentation. The getter and setter documentation should, however, still include full details about whether NULL values
are permissible for the function parameters, or are possible as the return value, for example.
Adding public API
=================
- Ensure it has proper guards against bad parameters:
g_return_if_fail (GDATA_IS_QUERY (self));
g_return_if_fail (foobar != NULL);
- All public API must have a gtk-doc comment, and be added to the docs/reference/gdata-sections.txt file, to include it in the documentation.
The documentation comment must have a "Since" clause (see "Documentation comments" section).
- All public API must be listed in gdata/gdata.symbols.
- Non-trivial API should have a test case added in the relevant test suite file in gdata/tests. Note that the "general" test suite file cannot make
network requests in the course of running its test cases.
- All GObject properties must have getter/setter functions.
- All API which returns allocated memory must be tagged with G_GNUC_WARN_UNUSED_RESULT after its declaration, to safeguard against consumers of the
API forgetting to use (and consequently free) the memory. This is unlikely, but adding the macro costs little and acts as a reminder in the API
documentation to free the result.
- All GObject *_get_type function declarations must be tagged with the G_GNUC_CONST macro, as well as any other applicable functions
(see the gcc documentation: http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html#index-g_t_0040code_007bconst_007d-function-attribute-2207).
- All properties which could be considered to use an enumerated value should almost definitely use a string instead. See the documentation section
on "Enumerable Properties" in the "GData Overview" section. Where appropriate, the values for these string properties should be made available
as #defines.
- New services should be implemented in libgdata itself, not by applications which use libgdata. See the documentation section on "New Services" in
the "GData Overview" section.
Choosing function names
=======================
In general, use common sense. However, there are some specific cases where a standard is enforced:
- For boolean getters (e.g. for FooBar:is-baz) use foo_bar_is_baz, rather than foo_bar_get_is_baz. Note that the property name should be "is-baz",
rather than just "baz".
- For boolean setters use foo_bar_set_is_baz, rather than foo_bar_set_baz.
- In general, try to keep API named similarly to the actual GData API constructs. In certain cases, however, it might make more sense to rename pieces
of API to be less cryptic (e.g. "timezone" instead of "ctz": http://code.google.com/apis/calendar/docs/2.0/reference.html#Parameters).
Commit messages
===============
libgdata does not use a ChangeLog; it is auto-generated from the git log when packaging a release. Commit messages should follow the GNOME commit
message guidelines (http://live.gnome.org/Git/CommitMessages), with the exception that when a commit closes a bug, the short explanation of the commit
should simply be the bug's title, as copied from Bugzilla (e.g. "Bug 579885 – Add code examples to documentation"). The long explanation should then
be used to give details of the changes. If the bug's title is not relevant, it should be changed before committing the changes.
The short explanation of a commit should always be prefixed by a tag to describe the part of the library it touches. The following tags are valid:
- [core] — for the core code in the gdata directory, such as GDataEntry.
- [atom] — for the Atom-namespaced code in the gdata/atom directory.
- [gcontact] — for the gContact-namespaced code in the gdata/gcontact directory.
- [gd] — for the GData-namespaced code in the gdata/gd directory.
- [media] — for the Media RSS-namespaced code in the gdata/media directory.
- [build] — for build changes and releases.
- [docs] — for documentation changes which are not specific to a service, such as updates to the docs directory, NEWS, README, this file, etc.
- [tests] — for changes to the test code in gdata/tests which are not specific to a service or namespace.
- [introspection] — for introspection annotations and build changes.
- [calendar] — for the Google Calendar code in gdata/services/calendar.
- [contacts] — for the Google Contacts code in gdata/services/contacts.
- [documents] — for the Google Documents code in gdata/services/documents.
- [picasaweb] — for the PicasaWeb code in gdata/services/picasaweb.
- [youtube] — for the YouTube code in gdata/services/youtube.
The only commits which should not have a tag are translation commits, touching only the po directory.
|
