commit b970f9b7a710d5f2e79da49b67ad72d02d23ec92
parent 8be09a841e309907fd7623c6f55ce45b8b8be7d7
Author: Evan Gates <evan.gates@gmail.com>
Date: Wed, 19 Nov 2014 13:51:34 -0800
add style.md
Diffstat:
| A | suckless.org/style.md | | | 142 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 142 insertions(+), 0 deletions(-)
diff --git a/suckless.org/style.md b/suckless.org/style.md
@@ -0,0 +1,142 @@
+Style
+=====
+Note that the following are guidelines and the most important aspect of style is consistency. Strive to keep your style consistent with the project on which you are working.
+
+Recommended Reading
+-------------------
+The following contain good information, some of which is repeated below, some of which is contradicted below.
+
+* <http://doc.cat-v.org/bell_labs/pikestyle>
+* <https://www.kernel.org/doc/Documentation/CodingStyle>
+* <http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man9/style.9?query=style&sec=9>
+
+File Layout
+-----------
+* Comment with LICENSE and possibly short explanation of file/tool
+* Headers
+* 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
+
+C Features
+----------
+* Use C99
+* Do not mix declarations and code
+* Do not use for loop initial declarations
+* Use `/* */` for comments, not `//`
+
+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, ...)
+* Use block for single statements iff
+ * Inner statement needs a block
+
+ for (;;) {
+ if (foo) {
+ bar;
+ baz;
+ }
+ }
+
+ * Another branch of same statement needs a block
+
+ if (foo) {
+ bar;
+ } else {
+ baz;
+ qux;
+ }
+
+Leading Whitespace
+------------------
+* Use tabs for indentation
+* 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
+
+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
+
+Variables
+---------
+* 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)
+
+Switch
+------
+* Do not indent cases another level
+* Comment cases that fall through
+
+Headers
+-------
+* Place system/libc headers first in alphabetical order
+ * 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
+ * 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)
+* Typedef structs
+* Do no 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;
+
+Line Length
+-----------
+* Keep lines to reasonable length (current debate as to reasonable)
+* If your lines are too long your code is likely too complex
+
+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)
+* Assign at declaration when possible
+
+ 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();
+
+Handling Errors
+---------------
+* When functions return -1 for error test against 0 not -1
+
+ if (func() < 0)
+ hcf();
+
+* Use goto to unwind and cleanup when necessary instead of multiple nested levels
+* return/exit/fail early instead of multiple nested levels
+* Think long and hard on whether or not you should cleanup on fatal errors
