HACKING.md 4.91 KB
Newer Older
Guido Gunther's avatar
Guido Gunther committed
1 2 3 4 5 6 7 8
Building
========
For build instructions see the README.md

Pull requests
=============
Before filing a pull request run the tests:

9 10 11
```sh
ninja -C _build test
```
Guido Gunther's avatar
Guido Gunther committed
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36

Use descriptive commit messages, see

   https://wiki.gnome.org/Git/CommitMessages

and check

   https://wiki.openstack.org/wiki/GitCommitMessages

for good examples.

Coding Style
============
We mostly use kernel style but

* Use spaces, never tabs
* Use 2 spaces for inentation

GTK+ style function argument indentation
----------------------------------------
Use GTK+ style function argument indentation. It's harder for renames but it's
what GNOME upstream projects do.

*Good*:

37 38 39 40 41
```c
static gboolean
button_clicked_cb (HdyDialerCycleButton *self,
                   GdkEventButton       *event)
```
Guido Gunther's avatar
Guido Gunther committed
42 43 44

*Bad*:

45 46 47 48
```c
static gboolean
button_clicked_cb (HdyDialerCycleButton *self, GdkEventButton *event)
```
Guido Gunther's avatar
Guido Gunther committed
49 50 51 52 53 54 55 56


Braces
------
Everything besides functions and structs have the opening curly brace on the same line.

*Good*:

57 58 59 60 61
```c
if (i < 0) {
    ...
}
```
Guido Gunther's avatar
Guido Gunther committed
62 63 64

*Bad*:

65 66 67 68 69 70
```c
if (i < 0)
{
    ...
}
```
Guido Gunther's avatar
Guido Gunther committed
71

72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127
Single line `if` or `else` statements don't need braces but if either `if` or
`else` have braces both get them:

*Good*:

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

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

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

*Bad*:

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

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

```c
if (i < 0)
  i++;
else {
  i--;
  j--;
}
```
Guido Gunther's avatar
Guido Gunther committed
128

129 130 131 132 133
Header Inclusion Guards
-----------------------
Guard header inclusion with `#pragma once` rather than the traditional
`#ifndef`-`#define`-`#endif` trio.

134 135 136 137 138 139 140 141 142 143 144
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(_HANDY_INSIDE) && !defined(HANDY_COMPILATION)
#error "Only <handy.h> can be included directly."
#endif
```

Only after these should you include headers.

145

Guido Gunther's avatar
Guido Gunther committed
146 147 148 149 150 151
Signals
-------
Prefix signal enum names with *SIGNAL_*.

*Good*:

152 153 154 155 156 157 158
```c
enum {
  SIGNAL_CYCLE_START = 0,
  SIGNAL_CYCLE_END,
  SIGNAL_LAST_SIGNAL,
};
```
Guido Gunther's avatar
Guido Gunther committed
159 160 161 162 163 164 165 166 167 168 169

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_*.

*Good*:

170 171 172 173 174 175 176
```c
enum {
  PROP_0 = 0,
  PROP_CYCLE_TIMEOUT,
  PROP_LAST_PROP,
};
```
Guido Gunther's avatar
Guido Gunther committed
177 178 179 180 181 182 183 184 185 186

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 and proper capitalization, punctation.

*Good*:

187 188 189
```c
/* Make sure we don't overflow. */
```
Guido Gunther's avatar
Guido Gunther committed
190 191 192

*Bad:*

193 194 195
```c
/* overflow check */
```
Guido Gunther's avatar
Guido Gunther committed
196 197 198 199 200 201 202 203


Callbacks
---------
Signal callbacks have a *_cb* suffix.

*Good*:

204 205 206
```c
g_signal_connect(self, "clicked", G_CALLBACK (button_clicked_cb), NULL);
```
Guido Gunther's avatar
Guido Gunther committed
207 208 209

*Bad*:

210 211 212
```c
g_signal_connect(self, "clicked", G_CALLBACK (handle_button_clicked), NULL);
```
Guido Gunther's avatar
Guido Gunther committed
213 214 215 216 217 218 219 220


Static functions
----------------
Static functions don't need the class prefix.  E.g. with a type foo_bar:

*Good*:

221 222 223 224 225
```c
static gboolean
button_clicked_cb (HdyDialerCycleButton *self,
                   GdkEventButton       *event)
```
Guido Gunther's avatar
Guido Gunther committed
226 227 228

*Bad*:

229 230 231 232 233
```c
static gboolean
foo_bar_button_clicked_cb (HdyDialerCycleButton *self,
                           GdkEventButton       *event)
```
Guido Gunther's avatar
Guido Gunther committed
234

235 236 237 238 239 240
Note however that virtual methods like
*<class_name>_{init,constructed,finalize,dispose}* do use the class prefix.
These functions are usually never called directly but only assigned once in
*<class_name>_constructed* so the longer name is kind of acceptable. This also
helps to distinguish virtual methods from regular private methods.

Guido Gunther's avatar
Guido Gunther committed
241 242 243 244 245 246 247
Self argument
-------------
The first argument is usually the object itself so call it *self*. E.g. for a
non public function:

*Good*:

248 249 250 251 252 253 254 255 256
```c
static gboolean
expire_cb (FooButton *self)
{
  g_return_val_if_fail (BAR_IS_FOO_BUTTON (self), FALSE);
  ...
  return FALSE;
}
```
Guido Gunther's avatar
Guido Gunther committed
257 258 259 260 261

And for a public function:

*Good*:

262 263 264 265 266
```c
gint
foo_button_get_state (FooButton *self)
{
  FooButtonPrivate *priv = bar_foo_get_instance_private(self);
Guido Gunther's avatar
Guido Gunther committed
267

268 269 270 271
  g_return_val_if_fail (BAR_IS_FOO_BUTTON (self), -1);
  return priv->state;
}
```
Guido Gunther's avatar
Guido Gunther committed
272 273 274 275 276 277 278 279 280 281 282 283

User interface files
--------------------
User interface files should end in *.ui*. If there are multiple ui
files put them in a ui/ subdirectory below the sources
(e.g. *src/ui/main-window.ui*).

### Properties
Use minus signs instead of underscores in property names:

*Good*:

284
```xml
285
<property name="margin-start">12</property>
286
```
Guido Gunther's avatar
Guido Gunther committed
287 288 289

*Bad":

290
```xml
291
<property name="margin_start">12</property>
292
```
293 294 295 296 297 298 299 300

Automatic cleanup
-----------------
It's recommended to use `g_auto()`, `g_autoptr()`, `g_autofree()` for
automatic resource cleanup when possible.

*Good*:

301 302 303
```c
g_autoptr(GdkPixbuf) sigterm = pixbuf = gtk_icon_info_load_icon (info, NULL);
```
304 305 306

*Bad*:

307 308 309 310 311
```c
GdkPixbuf *pixbuf = gtk_icon_info_load_icon (info, NULL);
...
g_object_unref (pixbuf);
```
312 313 314

Using the above is fine since libhandy doesn't target any older glib versions
or non GCC/Clang compilers at the moment.