From c7458e622d06a584b821a5a855d76559719a56e5 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Fri, 24 Apr 2009 18:29:22 +0100 Subject: [docs] Added a HACKING file --- HACKING | 136 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 HACKING (limited to 'HACKING') diff --git a/HACKING b/HACKING new file mode 100644 index 00000000..43cea4b4 --- /dev/null +++ b/HACKING @@ -0,0 +1,136 @@ +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 around 150 columns, such that it doesn't require horizontal scrolling on a decent-sized display. Don't wrap at 80 columns. + +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), format it as follows: + + * Return value: a new #GDataGDFeedLink, or %NULL; free with gdata_gd_feed_link_free() + + - 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 are mentioned in documentation as values to be passed around in code, they should be prefixed by a '%', just like %NULL. + +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). + +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. + + - [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. + + - [calendar] — for the Google Calendar code in gdata/services/calendar. + + - [contacts] — for the Google Contacts code in gdata/services/contacts. + + - [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. -- cgit v1.2.1