[retro-gtk] hacking: Document the coding style



commit 4c0e83ab14306bf59ce6c04bbd0c1c1c6e89509d
Author: Adrien Plazas <kekun plazas laposte net>
Date:   Sat Oct 17 22:25:39 2020 +0200

    hacking: Document the coding style

 HACKING.md | 546 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 546 insertions(+)
---
diff --git a/HACKING.md b/HACKING.md
index 5218e49b..5718ce8b 100644
--- a/HACKING.md
+++ b/HACKING.md
@@ -1,3 +1,549 @@
+## Coding Style
+
+### Identation
+
+Use 2 spaces for indentation, use spaces for alignment.
+
+### Parentheses
+
+Always put a single space before an opening parenthesis.
+
+### Function Definition
+
+Put attributes and the return type (including its asterisks) in a single line
+preceding the function's name.
+
+Good:
+```c
+static void
+function (FooBar *bar)
+```
+
+Bad:
+```c
+static void function (FooBar *bar)
+```
+
+Have a single parameter per line, the 1st parameter sitting on the same line as
+the function's name.
+Arrange the parameters into 4 columns:
+- the 1st column has the base types and is aligned left,
+- the 2nd column is a padding of a single space,
+- the 3rd column has the asterisks and is aligned right,
+- the last column has the parameter names.
+
+Good:
+```c
+static void
+function (FooBar  *bar,
+          char   **strings,
+          void    *data)
+```
+
+Bad:
+```c
+static void
+function (FooBar *bar,
+          char **strings,
+          void *data)
+```
+
+Bad:
+```c
+static void
+function (FooBar *bar, char **strings, void *data)
+```
+
+If the function has no parameter, explicit that with `void`.
+
+Good:
+```c
+static int
+function (void)
+```
+
+Bad:
+```c
+static int
+function ()
+```
+
+Functions have their opening curly brace on a new line.
+
+Good:
+```c
+static void
+function (…)
+{
+  …
+}
+```
+
+Bad:
+```c
+static void
+function (…) {
+  …
+}
+```
+
+### Function Order
+
+Functions are defined in the following order:
+- local functions
+- callback functions
+- overridden virtual methods
+- the class init function
+- the init function
+- for each implemented interface:
+  - interface methods
+  - interface init functions
+- public constructors
+- private constructors
+- public methods
+- private methods
+
+### Structures, Unions, and Enumerations
+
+Structures, unions, and enumerations have their opening curly brace on a new
+line.
+
+Good:
+```c
+struct FooBar
+{
+  …
+};
+```
+
+Good:
+```c
+typedef struct
+{
+  …
+} FooBar;
+```
+
+Bad:
+```c
+struct FooBar {
+  …
+};
+```
+
+Function calls and macro calls have a space between the function's name and the
+invocation parentheses.
+
+Good:
+```c
+foo_bar_get_state (FOO_BAR (self->bar));
+```
+
+Bad:
+```c
+foo_bar_get_state(FOO_BAR(self->bar));
+```
+
+### Conditional Statements
+
+Conditional statements must surround all their block with curly braces, unless
+all the blocks from the statement have a single line.
+
+Good:
+```c
+if (i < 0)
+  i++;
+else
+  i--;
+```
+
+Good:
+```c
+if (i < 0) {
+  i++;
+  j++;
+}
+else {
+  i--;
+}
+```
+
+Good:
+```c
+if (i < 0) {
+  i++;
+}
+else {
+  i--;
+  j--;
+}
+```
+
+Bad:
+```c
+if (i < 0) {
+  i++;
+}
+else {
+  i--;
+}
+```
+
+Bad:
+```c
+if (i < 0) {
+  i++;
+  j++;
+}
+else
+  i--;
+```
+
+Bad:
+```c
+if (i < 0)
+  i++;
+else {
+  i--;
+  j--;
+}
+```
+
+The `if`, `else`, and `else if` statements have their opening curly brace at the
+end of their last line, separated by a space.
+
+Good:
+```c
+if (i < 0) {
+  …
+}
+```
+
+Bad:
+```c
+if (i < 0)
+{
+  …
+}
+```
+
+The `else` and `else if` statements must not be on the same line as the previous
+closing curly brace.
+
+Good:
+```c
+if (…) {
+  …
+}
+else if (…) {
+  …
+}
+else {
+  …
+}
+```
+
+Bad:
+```c
+if (…) {
+  …
+} else if (…) {
+  …
+} else {
+  …
+}
+```
+
+# Type Casts
+
+Type casts must have a space between the closing parenthesis and the casted
+value.
+
+Good:
+```c
+name = (gchar *) data;
+```
+
+Bad:
+```c
+name = (gchar *)data;
+```
+
+### Switch Statements
+
+Switch statements have their opening curly brace at the end of the line,
+separated by a space.
+
+Good:
+```c
+switch (…) {
+  …
+}
+```
+
+Bad:
+```c
+switch (…)
+{
+  …
+}
+```
+
+The `case` statements have the same indentation as the `switch` statement, their
+block is indented as usual.
+
+Good:
+```c
+switch (…) {
+case …:
+  …
+}
+```
+
+Bad:
+```c
+switch (…) {
+  case …:
+    …
+}
+```
+
+### Header Inclusion Guards
+
+Guard header inclusion with `#pragma once` rather than the traditional
+`#ifndef`-`#define`-`#endif` trio.
+
+Internal headers (for consistency, whether they need to be installed or not)
+should contain the following guard to prevent users from directly including
+them:
+```c
+#if !defined(_FOO_INSIDE) && !defined(FOO_COMPILATION)
+#error "Only <foo.h> can be included directly."
+#endif
+```
+
+Only after these should you include headers.
+
+### Signals
+
+Prefix signal enum names with `SIGNAL_*`, except the signal count which must be
+named `N_SIGNALS`.
+
+Good:
+```c
+enum {
+  SIGNAL_SUBMITTED,
+  SIGNAL_DELETED,
+  SIGNAL_SYMBOL_CLICKED,
+  N_SIGNALS,
+};
+```
+
+Also note that the last element ends with a comma to reduce diff noise when
+adding further signals.
+
+### Properties
+
+Prefix property enum names with `PROP_*`, except the properties count which must
+be named `N_PROPS`.
+
+Good:
+```c
+enum {
+  PROP_0 = 0,
+  PROP_NUMBER,
+  PROP_SHOW_ACTION_BUTTONS,
+  PROP_COLUMN_SPACING,
+  PROP_ROW_SPACING,
+  PROP_RELIEF,
+  N_PROPS,
+};
+```
+
+Also note that the last element ends with a comma to reduce diff noise when
+adding further properties.
+
+### Comment Style
+
+In comments use full sentences with proper capitalization and punctuation.
+
+Good:
+```c
+/* Make sure we don't overflow. */
+```
+
+Bad:
+```c
+/* overflow check */
+```
+
+### Callbacks
+
+Suffix callback functions with `*_cb`, it must not have prefixes like `on_*`.
+
+Good:
+```c
+g_signal_connect (self, "clicked", G_CALLBACK (button_clicked_cb), NULL);
+```
+
+Bad:
+```c
+g_signal_connect (self, "clicked", G_CALLBACK (on_button_clicked), NULL);
+```
+
+Bad:
+```c
+g_signal_connect (self, "clicked", G_CALLBACK (on_button_clicked_cb), NULL);
+```
+
+Bad:
+```c
+g_signal_connect (self, "clicked", G_CALLBACK (handle_button_clicked), NULL);
+```
+
+### Static Functions
+
+Static functions don't need the class prefix.  E.g. with a type `foo_bar`.
+
+Good:
+```c
+static void
+button_clicked_cb (GtkButton *button)
+```
+
+Bad:
+```c
+static void
+foo_bar_button_clicked_cb (GtkButton *button)
+```
+
+Note however that virtual methods like
+`<class_name>_{init,constructed,finalize,dispose}` do take the class prefix.
+These functions are usually never called directly but only assigned once in
+`<class_name>_constructed` so the longer name is acceptable.
+This also helps to distinguish virtual methods from regular private methods and
+helper functions.
+
+### Self Argument
+
+The object a method is called on must be named `self`, including in callbacks.
+When possible, make it the first argument.
+When a method affects several objects of the same type in an equal manner, e.g.
+a comparison method, feel free to name the parameters `self` and `other`, or `a`
+and `b`.
+
+Good:
+```c
+static gboolean
+something_happened_cb (FooBar *self)
+{
+  g_return_val_if_fail (FOO_IS_BAR (self), FALSE);
+  …
+  return FALSE;
+}
+```
+
+And for a public function.
+
+Good:
+```c
+FooState *
+foo_bar_get_state (FooBar *self)
+{
+  FooBarPrivate *priv;
+
+  g_return_val_if_fail (FOO_IS_BAR (self), NULL);
+
+  priv = foo_bar_get_instance_private (self);
+
+  return priv->state;
+}
+```
+
+### Private Fields
+
+The private section of an object must not be retrieved before ensuring the
+object is valid.
+
+Good:
+```c
+FooState *
+foo_bar_get_state (FooBar *self)
+{
+  FooBarPrivate *priv;
+
+  g_return_val_if_fail (FOO_IS_BAR (self), NULL);
+
+  priv = foo_bar_get_instance_private (self);
+
+  return priv->state;
+}
+```
+
+Bad:
+```c
+FooState *
+foo_bar_get_state (FooBar *self)
+{
+  FooBarPrivate *priv = foo_bar_get_instance_private (self);
+
+  g_return_val_if_fail (FOO_IS_BAR (self), NULL);
+
+  return priv->state;
+}
+```
+
+### User interface files
+
+User interface template files should have the `.ui` extension, the same base
+name as other files of their class, and be localted at the same place as other
+files for that class.
+
+E.g.:
+```
+foo-bar.c
+foo-bar.h
+foo-bar-private.h
+foo-bar.ui
+```
+
+#### Properties
+
+Use minus signs instead of underscores in property names.
+
+Good:
+```xml
+<property name="margin-start">12</property>
+```
+
+Bad:
+```xml
+<property name="margin_start">12</property>
+```
+
+### Automatic cleanup
+
+It's recommended to use `g_auto()`, `g_autoptr()`, `g_autofree` for
+automatic resource cleanup when possible.
+Do not put a space between the attribute and its opening parenthesis.
+
+Good:
+```c
+g_autoptr(FooBaz) baz = foo_bar_generate_baz (bar);
+```
+
+Bad:
+```c
+g_autoptr (FooBaz) baz = foo_bar_generate_baz (bar);
+```
+
+Bad:
+```c
+FooBaz *baz = foo_bar_generate_baz (bar);
+…
+g_object_unref (baz);
+```
+
 ## Commit Message Style
 
 Commit messages have 4 parts: a tag, a short explanation, a long explanation,


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]