From 8fb30e6ec5fd65b1f5039d6aec029cdb43b99b88 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jonas=20=C3=85dahl?= <jadahl@gmail.com>
Date: Fri, 23 Oct 2020 20:47:01 +0200
Subject: README: Elaborate coding style and commit message guidelines

Spell out some conventions used in the README.

https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/1521
---
 README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 44 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 298fb87a6..cedaf25b4 100644
--- a/README.md
+++ b/README.md
@@ -29,17 +29,55 @@ To contribute, open merge requests at https://gitlab.gnome.org/GNOME/mutter.
 It can be useful to look at the documentation available at the
 [Wiki](https://gitlab.gnome.org/GNOME/mutter/-/wikis/home).
 
+## Coding style and conventions
+
 The coding style used is primarily the GNU flavor of the [GNOME coding
 style](https://developer.gnome.org/programming-guidelines/stable/c-coding-style.html.en)
-with some minor additions such as preferring regular C types and
-`stdint.h` types over GLib fundamental types, except for gboolean, and
-guint/gulong for GSource ids and signal handler ids. There is also a soft
-80 character line limit. However, in general, look at the file you're
-editing for inspiration.
+with some additions:
+
+ - Use regular C types and `stdint.h` types instead of GLib fundamental
+   types, except for `gboolean`, and `guint`/`gulong` for GSource ids and
+   signal handler ids. That means e.g. `uint64_t` instead of `guint64`, `int`
+   instead of `gint`, `unsigned int` instead of `guint` if unsignedness
+   is of importance, `uint8_t` instead of `guchar`, and so on.
+
+ - Try to to limit line length to 80 characters, although it's not a
+   strict limit.
+
+ - Usage of g_autofree and g_autoptr are encouraged. The style used is
+
+```c
+  g_autofree char *text = NULL;
+  g_autoptr (MetaSomeThing) thing = NULL;
+
+  text = g_strdup_printf ("The text: %d", a_number);
+  thing = g_object_new (META_TYPE_SOME_THING,
+                        "text", text,
+                        NULL);
+  thinger_use_thing (rocket, thing);
+```
+
+ - Declare variables at the top of the block they are used, but avoid
+   non-trivial logic among variable declarations. Non-trivial logic can be
+   getting a pointer that may be `NULL`, any kind of math, or anything
+   that may have side effects.
+
+ - Instead of boolean arguments in functions, prefer enums or flags when
+   they're more expressive.
+
+ - Use `g_new0()` etc instead of `g_slice_new0()`.
+
+ - Initialize and assign floating point variables (i.e. `float` or
+   `double`) using the form `floating_point = 3.14159` or `ratio = 2.0`.
+
+## Git messages
 
 Commit messages should follow the [GNOME commit message
 guidelines](https://wiki.gnome.org/Git/CommitMessages). We require an URL
-to either an issue or a merge request in each commit.
+to either an issue or a merge request in each commit. Try to always prefix
+commit subjects with a relevant topic, such as `compositor:` or
+`clutter/actor:`, and it's always better to write too much in the commit
+message body than too little.
 
 ## License
 
-- 
cgit v1.2.1