From a8aa7bae10d179708b89346bebb4bf7a93b8269f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jonas=20=C3=85dahl?= <jadahl@gmail.com>
Date: Wed, 27 Sep 2023 14:23:56 +0800
Subject: [PATCH] HACKING: Add note about object instance pointer naming

Mutter so far very rarely use the name `self`, so lets describe that in
the conventions document so that we can stay consistent.

Also mention how to deal with abstract/generic object instance pointers
vs sub type ones.

Part-of: <https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/3297>
---
 HACKING.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/HACKING.md b/HACKING.md
index 488e3127e..af9184a6c 100644
--- a/HACKING.md
+++ b/HACKING.md
@@ -52,6 +52,39 @@ style][gnome-coding-style], with some additions described below.
  * Initialize and assign floating point variables (i.e. `float` or
    `double`) using the form `floating_point = 3.14159` or `ratio = 2.0`.
 
+## Naming conventions
+
+ * For object instance pointers, use a descriptive name instead of `self`, e.g.
+
+```c
+G_DEFINE_TYPE (MetaPlaceholder, meta_placeholder, G_TYPE_OBJECT)
+
+...
+
+void
+meta_placeholder_hold_place (MetaPlaceholder *placeholder)
+{
+  ...
+}
+```
+
+ * When object instance pointers are pointers to non-generic implementations of
+   a generalized type, the convention is to suffix the variable name with the
+   sub-type name. E.g.
+
+```c
+G_DEFINE_TYPE (MetaPlaceholderWayland, meta_placeholder_wayland,
+               META_TYPE_PLACEHOLDER)
+
+...
+
+void
+meta_placeholder_wayland_get_waylandy (MetaPlaceholderWayland *placeholder_wayland)
+{
+  ...
+}
+```
+
 ## Header (.h) files
 
  * The return type and `*` are separated by a space.