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:

static void
function (FooBar *bar)

Bad:

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:

static void
function (FooBar  *bar,
          char   **strings,
          void    *data)

Bad:

static void
function (FooBar *bar,
          char **strings,
          void *data)

Bad:

static void
function (FooBar *bar, char **strings, void *data)

If the function has no parameter, explicit that with void.

Good:

static int
function (void)

Bad:

static int
function ()

Functions have their opening curly brace on a new line.

Good:

static void
function (…)
{
  …
}

Bad:

static void
function (…) {
  …
}

Function Result

If a public function transfers ownership of its returned value, explicit that by giving the function the G_GNUC_WARN_UNUSED_RESULT attribute.

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:

struct FooBar
{
  …
};

Good:

typedef struct
{
  …
} FooBar;

Bad:

struct FooBar {
  …
};

Function calls and macro calls have a space between the function's name and the invocation parentheses.

Good:

foo_bar_get_state (FOO_BAR (self->bar));

Bad:

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:

if (i < 0)
  i++;
else
  i--;

Good:

if (i < 0) {
  i++;
  j++;
}
else {
  i--;
}

Good:

if (i < 0) {
  i++;
}
else {
  i--;
  j--;
}

Bad:

if (i < 0) {
  i++;
}
else {
  i--;
}

Bad:

if (i < 0) {
  i++;
  j++;
}
else
  i--;

Bad:

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:

if (i < 0) {
  …
}

Bad:

if (i < 0)
{
  …
}

The else and else if statements must not be on the same line as the previous closing curly brace.

Good:

if (…) {
  …
}
else if (…) {
  …
}
else {
  …
}

Bad:

if (…) {
  …
} else if (…) {
  …
} else {
  …
}

Type Casts

Type casts must have a space between the closing parenthesis and the casted value.

Good:

name = (gchar *) data;

Bad:

name = (gchar *)data;

Switch Statements

Switch statements have their opening curly brace at the end of the line, separated by a space.

Good:

switch (…) {
  …
}

Bad:

switch (…)
{
  …
}

The case statements have the same indentation as the switch statement, their block is indented as usual.

Good:

switch (…) {
case …:
  …
}

Bad:

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:

#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:

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:

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:

/* Make sure we don't overflow. */

Bad:

/* overflow check */

Callbacks

Suffix callback functions with *_cb, it must not have prefixes like on_*.

Good:

g_signal_connect (self, "clicked", G_CALLBACK (button_clicked_cb), NULL);

Bad:

g_signal_connect (self, "clicked", G_CALLBACK (on_button_clicked), NULL);

Bad:

g_signal_connect (self, "clicked", G_CALLBACK (on_button_clicked_cb), NULL);

Bad:

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:

static void
button_clicked_cb (GtkButton *button)

Bad:

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:

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:

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:

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:

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:

<property name="margin-start">12</property>

Bad:

<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:

g_autoptr(FooBaz) baz = foo_bar_generate_baz (bar);

Bad:

g_autoptr (FooBaz) baz = foo_bar_generate_baz (bar);

Bad:

FooBaz *baz = foo_bar_generate_baz (bar);
…
g_object_unref (baz);

Documentation Style

XML Documentation

This describes how to write XML documentation like the reference manual.

Indent with two spaces.

Start paragraphs on a new line, indented. Break lines in paragraphs after 80 characters when possible, including the indentation. Start sentences on a new line so they can be changed without having to reflow the whole paragraph.

Don't break lines in the middle of inlined elements like links, only before or after. It is acceptable to let the element exceeds the 80 characters limit if you have no other choice, e.g. if a URL you are linking to is too long.

MarkDown Documentation

This describes how to write MarkDown documentation like README.md or HACKING.md.

Break lines in paragraphs after 80 characters when possible. Start sentences on a new line so they can be changed without having to reflow the whole paragraph.

Don't break lines in the middle of inlined elements like links, only before or after. It is acceptable to let the element exceeds the 80 characters limit if you have no other choice, e.g. if a URL you are linking to is too long.

Commit Message Style

Commit messages have 4 parts: a tag, a short explanation, a long explanation, and an issue reference.

tag: Short explanation of the commit

Longer explanation explaining exactly what's changed and why, whether
any external or private interfaces changed, what bugs were fixed (with
bug tracker reference if applicable) and so forth. Be concise but not
too brief.

Fixes https://gitlab.gnome.org/GNOME/retro-gtk/-/issues/1

The Tag

The tag tells which part of the software is affected; it must be in kebab-case, it shouldn't include fle extensions, and it shouldn't have the retro- prefix.

If the change is too global to be relevant to any specific part, you can omit the tag completely.

Good tags:

core-view
gtk
runner
meson
ci

Bad tags:

retro-core-view
retro-gtk
retro-runner
meson.build
CI

The Short Explanation

The short explanation must be brief and describe the change as shortly as possible. You should describe the change and not the intended effect, this is left to the long explanation. Use the imperative form, start with a capital letter (if relevant) and don't use terminal punctuation.

No need to prefix the full namespace to methods you mention if the type is in the tag already; you can refer to them via *_set_property() or via the set_property() method. No need to specify the accessors of a property, just mention the property's name.

The short explanation is the only part of a commit that can't be omitted.

Try to keep the first line (hence, the tag and the short explanation) under 50 characters, but longer lines are accepted if agreed they can't be shortened without losing useful information.

Good short explanations:

Add HACKING.md
gtk: Add RetroMyType
my-type: Add the my_method() method

Bad short explanations:

Add RetroMyType
gtk: Add RetroMyType.
gtk: add RetroMyType
gtk: This adds RetroMyType
my-type: Add retro_my_type_my_method()

The Long Explanation

The long explanations lets you describe anything that you deem important and can't be explained by the short explanation only. Use as many lines as you need, and leave an empty line between each paragraph. Try to limit the lines to 75 characters, but try to fill lines as much as possible withinh that limit. Do not break function names or URLs, give them their own line if they are too large to fit within the a single one.

Use proper prose with proper punctuation.

Good long explanations:

This gives retro_my_type_my_method() to RetroMyType to allow…

Bad long explanations:

Give retro_my_type_my_method()
to RetroMyType to allow…

The Issue Reference

If there is an issue fixed by your commit, specify it at the end of your commit message. It must be in the following format: Fixes $ISSUE_URL.

Do not simply use the issue number.

Good issue references:

Fixes https://gitlab.gnome.org/GNOME/retro-gtk/-/issues/1

Bad issue references:

Fixes #1
Fix https://gitlab.gnome.org/GNOME/retro-gtk/-/issues/1
Fixes https://gitlab.gnome.org/GNOME/retro-gtk/-/issues/1.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

HACKING.md

HACKING.md

Coding Style

Identation

Parentheses

Function Definition

Function Result

Function Order

Structures, Unions, and Enumerations

Conditional Statements

Type Casts

Switch Statements

Header Inclusion Guards

Signals

Properties

Comment Style

Callbacks

Static Functions

Self Argument

Private Fields

User interface files

Properties

Automatic cleanup

Documentation Style

XML Documentation

MarkDown Documentation

Commit Message Style

The Tag

The Short Explanation

The Long Explanation

The Issue Reference

Files

HACKING.md

Latest commit

History

HACKING.md

File metadata and controls

Coding Style

Identation

Parentheses

Function Definition

Function Result

Function Order

Structures, Unions, and Enumerations

Conditional Statements

Type Casts

Switch Statements

Header Inclusion Guards

Signals

Properties

Comment Style

Callbacks

Static Functions

Self Argument

Private Fields

User interface files

Properties

Automatic cleanup

Documentation Style

XML Documentation

MarkDown Documentation

Commit Message Style

The Tag

The Short Explanation

The Long Explanation

The Issue Reference