mirrors/labwc
1
0
Fork 0
mirror of https://github.com/labwc/labwc.git synced 2025-10-29 05:40:24 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

CONTRIBUTING.md: describe coding style more accurately

Browse source 
- Clarify the coding style relative to Linux kernel and Devault rules
- Add g_pattern_match_simple() example
- Add namespace advice and preference
- Elaborate on preferred header documentation style.
- Add table of contents
- Simplify API section and add wl_list_append()
This commit is contained in:
Johan Malm 2022-09-30 21:28:59 +01:00 • committed by Johan Malm
parent 89ad0b808f
commit 54b34e5bd7
1 changed files with 144 additions and 64 deletions
Download patch file Download diff file Expand all files Collapse all files

208
CONTRIBUTING.md
View file

@ -1,3 +1,18 @@
- [1. How to Contribute](#how-to-contribute)
- [2. Debugging](#debugging)
- [3. Packaging](#packaging)
- [4. Coding Style](#coding-style)
- [4.1 Linux Kernel Style Basics](#linux-kernel-style-basics)
- [4.2 Devault Deviations](#devault-deviations)
- [4.3 Labwc Specifics](#labwc-specifics)
- [4.3.1 API](#api)
- [4.3.2 The Use of glib](#the-use-of-glib)
- [4.3.3 The use of GNU extensions](#the-use-of-gnu-extensions)
- [4.3.4 Naming Conventions](#naming-conventions)
- [5. Commit Messages](#commit-messages)
- [6. Submitting Patches](#submitting-patches)
- [7. Native Language Support](#native-language-support)
# How to Contribute
1. Report bugs as github issues. We don't use a template, but try to provide
@ -75,19 +90,80 @@ to open an issue so we can add you to this list.
# Coding Style
labwc is written in Drew Devault's preferred [coding style] which is based
on the [Linux kernel coding style].
labwc is written in the [Linux kernel coding style] with a small number of
deviations to align with [Drew Devault's preferred coding style] nameley:
1. [Function Declaration](https://git.sr.ht/~sircmpwn/cstyle#function-declarations)
2. [Braces for one-line statement](https://git.sr.ht/~sircmpwn/cstyle#brace-placement)
3. [Organisation of header #include statements](https://git.sr.ht/~sircmpwn/cstyle#header-files)
4. [Breaking of long lines](https://git.sr.ht/~sircmpwn/cstyle#splitting-long-lines)
The reasons for specifying a style is not that we enjoy creating rules, but
because it makes reading/maintaining the code and spotting problems much easier.
If you're new to this style and want to get going quickly, either just imitate
If you are new to this style and want to get going quickly, either just imitate
the style around you, or read the summary below and use [checkpatch.pl] to run
some formatting checks.
## Style summary
## Linux Kernel Style Basics
Functions are defined as:
The preferred line length limit is 80 columns, although this is a bit soft.
Tabs are 8 columns wide. Identation with spaces is not used.
Opening braces go on the same line, except for function definitions.
Put `*` with the identifier when defining pointers, for example `char *foo`
Spaces are placed around binary operators but not unary, like this:
```
int x = y * (2 + z);
foo(--a, -b);
```
`sizeof(*foo)` is preferred over `sizeof(struct foo)`
Use `if (!p)` instead of `if (p == 0)` or `if (p == NULL)`
Comments are written as follows:
```
/* This is a single-line comment */
/*
* This is a multi-line comment which is much much much much much much
* longer.
*/
```
When documenting functions in header files we use the [kernel-doc format]:
```
/**
* function_name() - Brief description of function.
* @arg1: Describe the first argument.
* @arg2: Describe the second argument.
* One can provide multiple line descriptions
* for arguments.
*
* A longer description, with more discussion of the function function_name()
* that might be useful to those using or modifying it. Begins with an
* empty comment line, and may include additional embedded empty
* comment lines.
*
* The longer description may have multiple paragraphs.
*
* Return: Describe the return value of function_name.
*
* The return value description can also have multiple paragraphs, and should
* be placed at the end of the comment block.
*/
```
## Devault Deviations
Functions are defined as below with `name` on a new line:
```
return type
@ -97,8 +173,7 @@ name(parameters...)
}
```
Opening braces go on the same line, except for function definitions, and are
mandatory even for one-line statements.
Braces are mandatory even for one-line statements.
```
if (cond) {
@ -106,60 +181,38 @@ if (cond) {
}
```
Put * with the identifier when defining pointers: `char *foo`
Spaces are placed around binary operators `int x = y * (2 + z);`, but not unary
`foo(--a, -b);`
```
/* This is a single-line comment */
/*
* This is a multi-line comment which is much much much much much much
* longer.
*/
```
`#include` statements at the top of the file are organized by locality (`<>`
first, then `""`), then alphabetized.
The line length limit is 80 columns, although it is a bit soft.
Tabs are 8 columns wide. Identation with spaces is not used.
When breaking a statement onto several lines, indent the subsequent lines once.
If the statement declares a `{}` block, indent twice instead.
## labwc specifics
We prefer `sizeof(*foo)` over `sizeof(struct foo)`
We use `if (!p)` instead of `if (p == 0)` or `if (p == NULL)`
When documenting functions in header files we use the Linux kernel approach.
If the statement declares a `{}` block, indent twice instead. Also, place
operators (for example `&&`) on the next line.
```
/**
* foo - what foo does
* @var1: description of variable
* @var2: ditto
* Notes and further information
* Return value unless it is obvious
*/
if (seat->pressed.surface && ctx->surface != seat->pressed.surface
&& !update_pressed_surface(seat, ctx)
&& !seat->drag_icon) {
if (cursor_has_moved) {
process_cursor_motion_out_of_surface(server, time_msec);
}
return;
}
```
# API
## Labwc Specifics
### API
We have a very small, modest API and encourage you to use it.
1. [common/mem.h](https://github.com/labwc/labwc/blob/master/include/common/mem.h)
1. `znew()` - as a shorthand for calloc(1, sizeof()) with type checking
[common/mem.h]
Use `struct wlr_box *box = znew(*box);` instead of
`struct wlr_box *box = calloc(1, sizeof(struct wlr_box));`
2. `zfree()` to zero after free - [common/mem.h]
Use `zfree(foo)` instead of `free(foo)` to set foo=NULL.
3. `wl_list_append()` to add elements at end of lists - [common/list.h]
# The use of glib
### The Use of glib
We try to keep the use of glib pretty minimal for the following reasons:
@ -179,16 +232,32 @@ and can keep the code simpler.
For example, if we were going to carry out extensive string manipulation,
GString and utf8 helpers would be okay. Some functions such as
`g_utf8_casefold()` would be pretty hard to write from scratch and are fine to
use. Having said that, labwc does not do much string-work and thus far none of
these have been needed.
use. Having said that, labwc does not do much string-mangling.
The following functions are used today and are deemed acceptable by the core
devs:
- `g_shell_parse_argv()`
- `g_strsplit()`
- `g_pattern_match_simple()`
# The use of GNU extensions
When using these types of functions it is often desirable to support with some
glib code, which is okay provided it is kept local and self-contained. See
example from `src/theme.c`:
```
static bool
match(const gchar *pattern, const gchar *string)
{
GString *p = g_string_new(pattern);
g_string_ascii_down(p);
bool ret = (bool)g_pattern_match_simple(p->str, string);
g_string_free(p, true);
return ret;
}
```
### The use of GNU extensions
We avoid [GNU C extensions] because we want to fit into the eco-system
(wayland and wlroots) we live in.
@ -203,6 +272,27 @@ We compile with `-std=c11` because that's what 'wlroots' uses and we do not
want to increase the entry-level for OSs without good reason (and currently
we can't think of one).
### Naming Conventions
There are three types of coordinate systems: surface, output and layout - for
which the variables (sx, sy), (ox, oy) and (lx, ly) are used respectively in
line with wlroots.
With the introduction of the scene-graph API, some wlroots functions also use
node coordinates (nx, ny) but we prefer (sx, sy) where possible.
We do not worry about namespace issues too much and we try to not make the code
a pain to use just to uniquify names. If we were writing a library we would
prefix public functions and structs with `lab_`, but we are not. We do however
prefix public function names with the filename of the translation unit. For
example, public functions in `view.c` begin with `view_`.
We do start enums with `LAB_`
We use the prefix `handle_` for signal-handler-functions in order to be
consistent with sway and rootston. For example
`view->request_resize.notify = handle_request_resize`
# Commit Messages
The log messages that explain changes are just as important as the changes
@ -226,19 +316,6 @@ This first line should:
And please wrap the commit message at max 74 characters, otherwise `git log`
and similar look so weird. URLs and other references are exempt.
# Naming Convention
There are three types of coordinate systems: surface, output and layout - for
which the variables (sx, sy), (ox, oy) and (lx, ly) are used respectively in
line with wlroots.
With the introduction of the scene-graph API, some wlroots functions also use
node coordinates (nx, ny) but we prefer (sx, sy) where possible.
We use the prefix `handle_` for signal-handler-functions in order to be
consistent with sway and rootston. For example
`view->request_resize.notify = handle_request_resize`
# Submitting patches
Base both bugfixes and new features on `master`.
@ -258,8 +335,11 @@ xgettext --keyword=_ --language=C --add-comments -o po/labwc.pot src/menu/menu.c
[`wlroots/docs/env_vars.md`]: https://gitlab.freedesktop.org/wlroots/wlroots/-/blob/master/docs/env_vars.md
[wlhax]: https://git.sr.ht/~kennylevinsen/wlhax
[drm_info]: https://github.com/ascent12/drm_info
[coding style]: https://git.sr.ht/~sircmpwn/cstyle
[Drew Devault's preferred coding style]: https://git.sr.ht/~sircmpwn/cstyle
[Linux kernel coding style]: https://www.kernel.org/doc/html/v4.10/process/coding-style.html
[kernel-doc format]: https://docs.kernel.org/doc-guide/kernel-doc.html
[common/mem.h]: https://github.com/labwc/labwc/blob/master/include/common/mem.h
[common/list.h]: https://github.com/labwc/labwc/blob/master/include/common/list.h
[commit messages]: https://gitlab.freedesktop.org/wlroots/wlroots/-/blob/master/CONTRIBUTING.md#commit-messages
[checkpatch.pl]: https://github.com/johanmalm/checkpatch.pl
[GNU C extensions]: https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html