Code Guidelines - Revision history

Xaizek: /* Order of declarations */ Better title

2018-06-21T20:14:58Z

Order of declarations: Better title

Xaizek: /* C standard and GNU extensions */ Allow variable declarations not at block beginning.

2018-04-17T17:42:24Z

C standard and GNU extensions: Allow variable declarations not at block beginning.

Xaizek: /* Switch statement */ State formatting rules.

2015-09-05T14:53:34Z

Switch statement: State formatting rules.

Xaizek: /* C standard and GNU extensions */ Note use of _Exit().

2015-09-05T14:34:45Z

C standard and GNU extensions: Note use of _Exit().

Xaizek: /* C standard and GNU extensions */ Add to the list

2015-08-09T14:13:51Z

C standard and GNU extensions: Add <stdint.h> to the list

Xaizek: /* Braces */ Note mandatory use of braces

2015-08-09T13:24:39Z

Braces: Note mandatory use of braces

Xaizek: Initial version of the page

2015-08-09T08:33:37Z

Initial version of the page

New page

== General ==

=== Encoding ===

UTF-8, but without BOM.

=== Line endings ===

Unix.
With an empty line at end of file.

=== Trailing whitespace ===

Strictly forbidden.

=== Line length limitation ===

Up to 80 characters.
Verbose definitions of certain data structures can exceed this limit.

=== Header and footer ===

==== GNU comment ====

New files should have header that states license applied, copy from other files
and update the line with copyright.

==== Vim modeline ====

Each source file has Vim modeline settings to encode style when editing with
Vim, this should be copied into new files.

=== Empty lines ===

No more than one consequent.

== Indentation ==

=== General ===

Tabulation, which can be followed by spaces to get something like this:
<source lang="c">
return (entry->ENGINE== FT_DIR)
|| (entry->type == FT_LINK &&
get_symlink_type(entry->name) != SLT_UNKNOWN);
</source>

==== For regular lines ====

==== For wrapped lines ====

=== Switch statement ===

<code>case</code> is indented as well as what goes after it, e.g.:
<source lang="c">
switch(scope)
{
case FLS_SELECTION:
move_cursor_out_of_scope(view, &is_entry_selected);
break;
case FLS_MARKING:
move_cursor_out_of_scope(view, &is_entry_marked);
break;

default:
assert(0 && "Unhandled file list scope type");
break;
}
</source>

== Formatting ==

=== Braces ===

Braces are on their own lines, except for data assignment, so we have
<source lang="c">
/* Custom argument for is_in_list() function. */
typedef struct
{
int nitems; /* Number of items in the list. */
char **items; /* The list itself. */
}
list_t;
</source>
but:
<source lang="c">
const struct timeval ts_init = { .tv_sec = 0, .tv_usec = 1000 };
</source>
and
<source lang="c">
get_mount_point_traverser_state state = {
.type = MI_FS_TYPE,
.path = full_path,
.buf_len = sizeof(fs_name),
.buf = fs_name,
.curr_len = 0UL,
};
</source>

=== Spacing ===

Commas should be followed by a space.
Binary plus and minus signs should be surrounded with spaces.
Keywords that are followed by open parenthesis, like <code>if</code>,
<code>while</code>, <code>switch</code> should not be separated with a space
from the parenthesis.

=== Alignment ===

== Comments ==

Only multiline comments of C90 should be used.
<code>/*</code> and <code>*/</code> , no <code>//</code> allowed.
First letter must be capitalized.
Sentences should end with a dot.
No need for dedicated lines for <code>/*</code> or <code>*/</code>.
Example:
<source lang="c">
/* Ensure trash directories exist, it might not have been called during
* configuration file sourcing if there is no `set trashdir=...` command. */
</source>

=== Function comments ===

Non-static functions should have comments in corresponding header.
Static functions should be commented where they are defined.

Comments are of free form (not Doxygen), but should include two things:
* what the function does;
* what it returns on success and error (if return type is not <code>void</code>).

Example:
<source lang="c">
/* Checks whether pair is being used at the moment. Returns non-zero if so and
* zero otherwise. */
</source>

It should be "Checks" and "Returns", not "Check" and "Return".

=== Item comments of union, struct or enum ===

== Naming ==

=== Functions and variables ===

Words in lower case separated with underscores.

=== Macros ===

Words in upper case separated with underscores.

=== Types ===

Usualy have <code>_t</code> suffix.

=== Prefixes ===

Some units have prefix for all names defined in them, ideally all of them should
have such prefixes, but it's not the case yet. When editing such units,
preserve prefixes.

== Function definitions ==

Return type should be on a separate line along with <code>static</code> keyword:
<source lang="c">
void
get_perm_string(char buf[], int len, mode_t mode)
{
...
}
</source>

== Include directives ==

=== Order of groups ===

# Header of the current file
# Third-party library headers in arbitrary order
# System headers
# Local headers

=== Order of elements within groups ===

# Directories go first
# All includes are in alphabetic order

=== Additional information ===

It's a good point to write list of used symbols in comments along with include
of system headers.

== Header files ==

=== Header guard ===

PREFIX ::= VIFM | VIFM_TESTS

{PREFIX}{__DIR_NAME}__FILE_NAME_H__

Example:
<source lang="c">
#ifndef VIFM__BRACKET_NOTATION_H__
#define VIFM__BRACKET_NOTATION_H__
...
#endif /* VIFM__BRACKET_NOTATION_H__ */
</source>

== Tests ==

== Other ==

=== Order of declarations ===

# Types
# Functions
# Variables

=== Order of functions ===

When possible, callee should follow caller in the code.

=== Size of function body ===

=== Type declarations ===

==== Pointers ====

In return types:
<source lang="c">
wchar_t * to_wide(const char s[]);
</source>
For variables:
<source lang="c">
wchar_t *result = NULL;
</source>

==== Pointers to arrays ====

In parameter list, such pointers should be written as
<source lang="c">
type name[]
</source>
instead of
<source lang="c">
type *name
</source>

==== Enumerations ====

==== Structures ====

==== Unions ====

==== Other typedefs ====

=== Variable declarations ===

==== Using size_t type ====

==== Arrays in function argument list ====

==== Constness of function arguments ====

==== Constness of local variables ====

=== Literals ===

==== Character literals ====

==== Comparison with zero or non zero ====

=== C standard and GNU extensions ===

It's mostly GNUC.
Variable declarations are like in C90.
Designated initializers and expression statements are used in the code.

@@ Line 289: / Line 289: @@
 === C standard and GNU extensions ===
-It's mostly GNUC.
+It's GNU dialect of C.
-Variable declarations are like in C90.
-Designated initializers, expression statements, <code>_Exit()</code> and <code>&lt;stdint.h&gt;</code> are used in the code.
+Variable declarations are mostly in C90 style and declared at the beginning of code blocks, but declarations after statements are allowed too.

@@ Line 286: / Line 286: @@
 It's mostly GNUC.
 Variable declarations are like in C90.
-Designated initializers, expression statements and <code>&lt;stdint.h&gt;</code> are used in the code.
+Designated initializers, expression statements, <code>_Exit()</code> and <code>&lt;stdint.h&gt;</code> are used in the code.

@@ Line 227: / Line 227: @@
 == Other ==
-=== Order of declarations ===
+=== Order of declarations in a file ===
 # Types

@@ Line 52: / Line 52: @@
 === Switch statement ===
-<code>case</code> is indented as well as what goes after it, e.g.:
+* <code>case</code> is indented as well as what goes after it, except for very rare cases there is no need for empty lines between <code>case</code> statements.
 <source lang="c">
 switch(scope)

@@ Line 41: / Line 41: @@
 Tabulation, which can be followed by spaces to get something like this:
 <source lang="c">
-	return (entry->ENGINE== FT_DIR)
+	return (entry->type == FT_DIR)
 	    || (entry->type == FT_LINK &&
 	        get_symlink_type(entry->name) != SLT_UNKNOWN);
@@ Line 72: / Line 72: @@
 === Braces ===
 Braces are on their own lines, except for data assignment, so we have