logo

blog

My cute blog can’t be this disorganised!

coding style.shtml (7057B)


      1 <!DOCTYPE html>
      2 <html>
      3 	<head>
      4 <!--#include file="/templates/head.shtml" -->
      5 		<title>Coding Style — lanodan’s cyber-home</title>
      6 	</head>
      7 	<body>
      8 <!--#include file="/templates/en/nav.shtml" -->
      9 		<main>
     10 			<h1>Coding Style</h1>
     11 			<p>This is taken from &copy; 2006-2015 <a href="//suckless.org">suckless.org</a> community, with few modifications because no coder have the same style.</p>
     12 			<p>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.</p>
     13 			<h2>Recommended Reading</h2>
     14 			<p>The following contain good information, some of which is repeated below, some of which is contradicted below.</p>
     15 			<ul>
     16 				<li><a href="http://doc.cat-v.org/bell_labs/pikestyle">http://doc.cat-v.org/bell_labs/pikestyle</a></li>
     17 				<li><a href="https://www.kernel.org/doc/Documentation/CodingStyle">https://www.kernel.org/doc/Documentation/CodingStyle</a></li>
     18 				<li><a href="http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man9/style.9?query=style&amp;sec=9">http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man9/style.9?query=style&amp;sec=9</a></li>
     19 			</ul>
     20 			
     21 			
     22 			<h2>File Layout</h2>
     23 			<ul>
     24 			<li>Comment with LICENSE and possibly short explanation of file/tool</li>
     25 			<li>Headers</li>
     26 			<li>Macros</li>
     27 			<li>Types</li>
     28 			<li>Function declarations<ul>
     29 				<li>Include variable names</li>
     30 				<li>For short files these can be left out</li>
     31 				<li>Group/order in logical manner</li>
     32 			</ul></li>
     33 				<li>Global variables</li>
     34 				<li>Function definitions in same order as declarations</li>
     35 				<li><code>main</code></li>
     36 			</ul>
     37 			<h2>C Features</h2>
     38 			<ul>
     39 				<li>Use C99 without extensions (ISO/IEC 9899:1999)<ul>
     40 					<li>When using gcc compile with -std=c99 -pedantic</li>
     41 				</ul></li>
     42 				<li>Use POSIX.1-2008<ul>
     43 					<li>When using gcc define <code>_POSIX_C_SOURCE 200809L</code></li>
     44 					<li>Alternatively define <code>_XOPEN_SOURCE 700</code></li>
     45 				</ul></li>
     46 				<li>Do not mix declarations and code</li>
     47 				<li>Do not use for loop initial declarations</li>
     48 				<li>Use <code>/* */</code> for comments, not <code>//</code></li>
     49 				<li>Variadic macros are acceptable, but remember<ul>
     50 					<li><code>__VA_ARGS__</code> not a named parameter</li>
     51 					<li>Arg list cannot be empty</li>
     52 				</ul></li>
     53 			</ul>
     54 			<h2>Blocks</h2>
     55 			<ul>
     56 				<li>All variable declarations at top of block</li>
     57 				<li><code>{</code> on same line preceded by single space</li>
     58 				<li><code>}</code> on own line unless continuing statement (<code>if else</code>, <code>do while</code>, &hellip;)</li>
     59 				<li>Use block for single statements iff<ul>
     60 					<li><p>Inner statement needs a block</p>
     61 <pre><code>for (;;) {
     62 	if (foo) {
     63 		bar;
     64 		baz;
     65 	}
     66 }
     67 </code></pre></li>
     68 					<li><p>Another branch of same statement needs a block</p>
     69 <pre><code>if (foo) {
     70 	bar;
     71 } else {
     72 	baz;
     73 	qux;
     74 }
     75 </code></pre></li>
     76 				</ul></li>
     77 			</ul>
     78 			<h2>Leading Whitespace</h2>
     79 			<ul>
     80 				<li>Use tabs for indentation</li>
     81 				<li>Use spaces for alignment<ul>
     82 					<li>This means no tabs except beginning of line</li>
     83 					<li>Everything will line up independent of tab size</li>
     84 					<li>Use spaces not tabs for multiline macros as the indentation level is 0, where the <code>#define</code> began</li>
     85 				</ul></li>
     86 			</ul>
     87 			<h2>Functions</h2>
     88 			<ul>
     89 				<li>Return type and modifiers on own line</li>
     90 				<li>Function name and argument list on next line</li>
     91 				<li>Opening <code>{</code> on own line (function definitions are a special case of blocks as they cannot be nested)</li>
     92 				<li>Functions not used outside translation unit should be declared and defined <code>static</code></li>
     93 			</ul>
     94 			<h2>Variables</h2>
     95 			<ul>
     96 				<li>Global variables not used outside translation unit should be declared <code>static</code></li>
     97 				<li>In declaration of pointers the <code>*</code> is adjacent to variable name, not type</li>
     98 			</ul>
     99 			<h2>Keywords</h2>
    100 			<ul>
    101 				<li>Do not use a space after the opening <code>(</code> and before the closing <code>)</code></li>
    102 				<li>Always use <code>()</code> with <code>sizeof</code></li>
    103 			</ul>
    104 			<h2>Switch</h2>
    105 			<ul>
    106 				<li>indent cases another level</li>
    107 				<li>Comment cases that FALLTHROUGH</li>
    108 			</ul>
    109 			<h2>Headers</h2>
    110 			<ul>
    111 				<li>Place system/libc headers first in alphabetical order<ul>
    112 					<li>If headers must be included in a specific order comment to explain</li>
    113 				</ul></li>
    114 				<li>Place local headers after an empty line</li>
    115 				<li>When writing and using local headers<ul>
    116 					<li>Do not use <code>#ifndef</code> guards</li>
    117 					<li>Instead ensure they are included where and when they are needed</li>
    118 					<li>Read <a href="https://talks.golang.org/2012/splash.article#TOC_5.">https://talks.golang.org/2012/splash.article#TOC_5.</a></li>
    119 					<li>Read <a href="http://plan9.bell-labs.com/sys/doc/comp.html">http://plan9.bell-labs.com/sys/doc/comp.html</a></li>
    120 				</ul></li>
    121 			</ul>
    122 			<h2>User Defined Types</h2>
    123 			<ul>
    124 				<li>Do not use <code>type_t</code> naming (it is reserved for POSIX and less readable)</li>
    125 				<li>Typedef structs</li>
    126 				<li>Do not typedef builtin types</li>
    127 				<li>Capitalize the type name</li>
    128 				<li><p>Typedef the type name, if possible without first naming the struct</p>
    129 <pre><code>typedef struct {
    130 	double x, y, z;
    131 } Point;
    132 </code></pre></li>
    133 			</ul>
    134 			<h2>Line Length</h2>
    135 			<ul>
    136 				<li>Keep lines to reasonable length (current debate as to reasonable)</li>
    137 				<li>If your lines are too long your code is likely too complex</li>
    138 			</ul>
    139 			<h2>Tests and Boolean Values</h2>
    140 			<ul>
    141 				<li>Do not test against <code>NULL</code> explicitly</li>
    142 				<li>Do not test against <code>0</code> explicitly</li>
    143 				<li>Do not use <code>bool</code> types (stick to integer types)</li>
    144 				<li><p>Assign at declaration when possible</p>
    145 <pre><code>Type *p = malloc(sizeof(*p));
    146 if (!p)
    147 	hcf();
    148 </code></pre></li>
    149 				<li><p>Otherwise use compound assignment and tests unless the line grows too long</p>
    150 <pre><code>if (!(p = malloc(sizeof(*p))))
    151 	hcf();
    152 </code></pre></li>
    153 			</ul>
    154 			<h2>Handling Errors</h2>
    155 			<ul>
    156 				<li><p>When functions <code>return -1</code> for error test against <code>0</code> not <code>-1</code></p>
    157 <pre><code>if (func() &lt; 0)
    158 	hcf();
    159 </code></pre></li>
    160 				<li>Use <code>goto</code> to unwind and cleanup when necessary instead of multiple nested levels</li>
    161 				<li><code>return</code> or <code>exit</code> early on failures instead of multiple nested levels</li>
    162 				<li>Unreachable code should have a NOTREACHED comment</li>
    163 				<li>Think long and hard on whether or not you should cleanup on fatal errors</li>
    164 			</ul>
    165 			<h2>Enums vs #define</h2>
    166 			<ul>
    167 				<li><p>Use enums for values that are grouped semantically and #define otherwise.</p>
    168 <pre><code>#define MAXSZ  4096
    169 #define MAGIC1 0xdeadbeef
    170 
    171 enum {
    172 	DIRECTION_X,
    173 	DIRECTION_Y,
    174 	DIRECTION_Z
    175 };
    176 </code></pre></li>
    177 			</ul>
    178 		</main>
    179 <!--#include file="/templates/en/footer.html" -->
    180 	</body>
    181 </html>