commit 0659a257b8a829317852a25fb38f9f285491e094
Author: Evan Gates <[email protected]>
Date: Thu Nov 20 10:43:44 2014 -0800
fix code blocks, add a bit about C versions, other cleanup
diff --git a/suckless.org/style.md b/suckless.org/style.md
index 74b6232..f5b494c 100644
--- a/suckless.org/style.md
+++ b/suckless.org/style.md
@@ -17,43 +17,49 @@ File Layout
* Macros
* Types
* Function declarations
- * Include variable names
- * For short files these can be left out
- * Group/order in logical manner
-* Global Variables
-* Function Definitions in same order as declarations
-* main
+ * Include variable names
+ * For short files these can be left out
+ * Group/order in logical manner
+* Global variables
+* Function definitions in same order as declarations
+* `main`
C Features
----------
-* Use C99
+* Use C99 without extensions (ISO/IEC 9899:1999)
+ * When using gcc compile with -std=c99 -pedantic
+* Use POSIX.1-2008
+ * When using gcc define `_POSIX_C_SOURCE 200809L`
+ * Alternatively define `_XOPEN_SOURCE 700`
* Do not mix declarations and code
* Do not use for loop initial declarations
* Use `/* */` for comments, not `//`
+* Variadic macros are acceptable, but remember
+ * __VA_ARGS__ not a named parameter
+ * Arg list cannot be empty
Blocks
------
* All variable declarations at top of block
-* { on same line preceded by single space (except functions)
-* } on own line unless continuing statement (if else, do while, ...)
+* `{` on same line preceded by single space (except functions)
+* `}` on own line unless continuing statement (`if else`, `do while`, ...)
* Use block for single statements iff
* Inner statement needs a block
- for (;;) {
- if (foo) {
- bar;
- baz;
- }
- }
-
+ for (;;) {
+ if (foo) {
+ bar;
+ baz;
+ }
+ }
* Another branch of same statement needs a block
- if (foo) {
- bar;
- } else {
- baz;
- qux;
- }
+ if (foo) {
+ bar;
+ } else {
+ baz;
+ qux;
+ }
Leading Whitespace
------------------
@@ -61,26 +67,26 @@ Leading Whitespace
* Use spaces for alignment
* This means no tabs except beginning of line
* Everything will line up independent of tab size
- * Use spaces not tabs for multiline macros as the indentation level is
0, where the #define began
+ * Use spaces not tabs for multiline macros as the indentation level is
0, where the `#define` began
Functions
---------
* Return type and modifiers on own line
* Function name and argument list on next line
-* Opening { on own line (function definitions are a special case of blocks as
they cannot be nested)
-* Functions not used outside translation unit should be declared/defined static
+* Opening `{` on own line (function definitions are a special case of blocks
as they cannot be nested)
+* Functions not used outside translation unit should be declared and defined
`static`
Variables
---------
-* Global variables not used outside translation unit should be declared static
-* In declaration of pointers the * is adjacent to variable name, not type
+* Global variables not used outside translation unit should be declared
`static`
+* In declaration of pointers the `*` is adjacent to variable name, not type
Keywords
--------
-* Use a space after if, for, while, switch (they are not function calls)
-* Do not use a space after the opening ( and before the closing )
-* Always use () with sizeof
-* Do not use a space with sizeof() (it does act like a function call)
+* Use a space after `if`, `for`, `while`, `switch` (they are not function
calls)
+* Do not use a space after the opening `(` and before the closing `)`
+* Always use `()` with `sizeof`
+* Do not use a space with `sizeof()` (it does act like a function call)
Switch
------
@@ -93,21 +99,22 @@ Headers
* If headers must be included in a specific order comment to explain
* Place local headers after an empty line
* When writing and using local headers
- * Do not use ifndef/define guards
+ * Do not use `#ifndef` guards
* Instead ensure they are included where and when they are needed
* Read <https://talks.golang.org/2012/splash.article#TOC_5.>
* Read <http://plan9.bell-labs.com/sys/doc/comp.html>
User Defined Types
------------------
-* Do not use type_t naming (it is reserved for POSIX and less readable)
+* Do not use `type_t` naming (it is reserved for POSIX and less readable)
* Typedef structs
-* Do no typedef builtin types
+* Do not typedef builtin types
* Capitalize the type name
* Typedef the type name, if possible without first naming the struct
- typedef struct {
- double x, y, z;
- } Point;
+
+ typedef struct {
+ double x, y, z;
+ } Point;
Line Length
-----------
@@ -116,27 +123,25 @@ Line Length
Tests and Boolean Values
------------------------
-* Do not test against NULL explicitly
-* Do not test against 0 explicitly
-* Do not use bool types (stick to integer types)
+* Do not test against `NULL` explicitly
+* Do not test against `0` explicitly
+* Do not use `bool` types (stick to integer types)
* Assign at declaration when possible
- Type *p = malloc(sizeof(*p));
- if (!p)
- hcf();
-
+ Type *p = malloc(sizeof(*p));
+ if (!p)
+ hcf();
* Otherwise use compound assignment and tests unless the line grows too long
- if (!(p = malloc(sizeof(*p))))
- hcf();
+ if (!(p = malloc(sizeof(*p))))
+ hcf();
Handling Errors
---------------
-* When functions return -1 for error test against 0 not -1
-
- if (func() < 0)
- hcf();
+* When functions `return -1` for error test against `0` not `-1`
-* Use goto to unwind and cleanup when necessary instead of multiple nested
levels
-* return/exit/fail early instead of multiple nested levels
+ if (func() < 0)
+ hcf();
+* Use `goto` to unwind and cleanup when necessary instead of multiple nested
levels
+* `return` or `exit` early on failures instead of multiple nested levels
* Think long and hard on whether or not you should cleanup on fatal errors
