Annotation of prex/doc/html/doc/standard.html, Revision 1.1.1.1
1.1 nbrk 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2: <html>
3: <head>
4: <title>Prex Coding Standard</title>
5: <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
6: <meta name="keywords" content="Prex, embedded, real-time, operating system, RTOS, open source, free">
7: <meta name="author" content="Kohsuke Ohtani">
8: <link rel="stylesheet" type="text/css" href="../default.css" media="screen">
9: <link rel="stylesheet" type="text/css" href="../print.css" media="print">
10: </head>
11: <body>
12: <div id="top">
13: </div>
14: <div id="middle">
15:
16: <table id="content" cellpadding="0" cellspacing="0">
17: <tbody>
18:
19: <tr>
20: <td id="header" colspan="2" valign="top">
21: <table width="100%" border="0" cellspacing="0" cellpadding="0">
22: <tr>
23: <td id="logo">
24: <a href="http://prex.sourceforge.net/">
25: <img alt="Prex logo" src="../img/logo.gif" border="0"
26: style="width: 250px; height: 54px;"></a>
27: </td>
28: <td id="brief" align="right" valign="bottom">
29: An Open Source, Royalty-free,<br>
30: Real-time Operating System
31: </td>
32: </tr>
33: </table>
34: </td>
35: </tr>
36:
37: <tr>
38: <td id="directory" style="vertical-align: top;">
39: <a href="http://prex.sourceforge.net/">Prex Home</a> >
40: <a href="index.html">Document Index</a> >
41: Coding Standard
42: </tr>
43: <tr><td class="pad" colspan="2" style="vertical-align: top;"></td></tr>
44:
45: <tr>
46: <td id="doc" style="vertical-align: top;">
47: <h1>Prex Coding Standard</h1>
48:
49: <i>Version 1.0 2008/06/14</i><br><br>
50:
51: <pre class="raw">
52: /*
53: * Prex Coding Standard
54: *
55: * Based on the CSRG's KNF (Kernel Normal Form) and FreeBSD's style guide
56: *
57: * @(#)style 1.14 (Berkeley) 4/28/95
58: */
59:
60: /*
61: * VERY important single-line comments look like this.
62: */
63:
64: /* Most single-line comments look like this. */
65:
66: /*
67: * Multi-line comments look like this. Make them real sentences.
68: * Fill them so they look like real paragraphs.
69: */
70:
71: /* Don't use C-99 style "// ..." comments. */
72:
73: /*
74: * Attempt to wrap lines longer than 80 characters appropriately.
75: * Comments should not be enclosed in large boxes drawn with asterisks
76: * or other characters.
77: */
78:
79: /*
80: * The copyright header should be a multi-line comment, with the first
81: * line of the comment having a dash after the star like so:
82: */
83:
84: /*-
85: * Copyright (c) 1984-2025 John Q. Public
86: * All rights reserved.
87: *
88: * Long, boring license goes here, but redacted for brevity
89: */
90:
91: /* After any copyright header, there is a blank line. */
92:
93: /*
94: * Kernel include files come first.
95: */
96: #include <sys/types.h> /* Non-local includes in brackets. */
97:
98: /*
99: * Then there's a blank line, followed by the /usr include files.
100: */
101: #include <stdio.h>
102:
103: /*
104: * Global pathnames are defined in /usr/include/paths.h. Pathnames
105: * local to the program go in pathnames.h in the local directory.
106: */
107: #include <paths.h>
108:
109: /* Then, there's a blank line, and the user include files. */
110: #include "pathnames.h" /* Local includes in double quotes. */
111:
112: /*
113: * The names of ``unsafe'' macros (ones that have side effects), and
114: * the names of macros for manifest constants, are all in uppercase.
115: * The expansions of expression-like macros are either a single token
116: * or have outer parentheses. Put a single tab character between the
117: * #define and the macro name. If the macro encapsulates a compound
118: * statement, enclose it in a do loop, so that it can safely be used
119: * in if statements. Any final statement-terminating semicolon should
120: * be supplied by the macro invocation rather than the macro, to make
121: * parsing easier for pretty-printers and editors.
122: */
123: #define MACRO(x, y) \
124: do { \
125: variable = (x) + (y); \
126: (y) += 2; \
127: } while (0)
128:
129: /* Enum types are capitalized. */
130: enum enumtype {
131: ONE,
132: TWO
133: } et;
134:
135: /*
136: * In declarations, do not put any whitespace between asterisks and
137: * adjacent tokens, except for tokens that are identifiers related to
138: * types. (These identifiers are the names of basic types, type
139: * qualifiers, and typedef-names other than the one being declared.)
140: * Separate these identi- fiers from asterisks using a single space.
141: */
142:
143: /*
144: * When declaring variables in structures, each one gets its own line.
145: * Try to make the structure readable by aligning the member names
146: * using either one or two tabs depending upon your judgment. You
147: * should use one tab only if it suffices to align at least 90% of the
148: * member names. Names following extremely long types should be
149: * separated by a single space.
150: *
151: * Major structures should be declared at the top of the file in which
152: * they are used, or in separate header files, if they are used in
153: * multiple source files. Use of the structures should be by separate
154: * declarations and should be "extern" if they are declared in a
155: * header file.
156: */
157: struct foo {
158: struct foo *next; /* list of active foo */
159: struct mumble amumble; /* comment for mumble */
160: int bar; /* try to align the comments */
161: struct verylongtypename *baz; /* won't fit in 2 tabs */
162: };
163: struct foo *foohead; /* head of global foo list */
164:
165: /*
166: * Prototypes should not have variable names associated with the types.
167: * Prototypes may have an extra space after a tab to enable function
168: * names to line up:
169: */
170: static char *function(int, const char *);
171: static void usage(void);
172:
173: /* C99 uintN_t is preferred over u_intN_t. */
174: uint32_t zero;
175:
176: /*
177: * All major routines should have a comment briefly describing what
178: * they do. The comment before the "main" routine should describe
179: * what the program does.
180: */
181: int
182: main(int argc, char *argv[])
183: {
184: long num;
185: int ch;
186: char *ep;
187:
188: /*
189: * For consistency, getopt should be used to parse options.
190: * Options should be sorted in the getopt call and the switch
191: * statement, unless parts of the switch cascade. Elements in
192: * a switch statement that cascade should have a FALLTHROUGH
193: * comment. Numerical arguments should be checked for
194: * accuracy. Code that cannot be reached should have a
195: * NOTREACHED comment.
196: */
197: while ((ch = getopt(argc, argv, "abn")) != -1) {
198: switch (ch) { /* Indent the switch. */
199: case 'a': /* Don't indent the case. */
200: aflag = 1;
201: /* FALLTHROUGH */
202: case 'b':
203: bflag = 1;
204: break;
205: case 'n':
206: num = strtol(optarg, &ep, 10);
207: if (num <= 0 || *ep != '\0')
208: err("illegal number -- %s", optarg);
209: break;
210: case '?':
211: default:
212: usage();
213: /* NOTREACHED */
214: }
215: }
216: argc -= optind;
217: argv += optind;
218:
219: /*
220: * Use a space after keywords (if, while, for, return, switch).
221: * No braces are required for control statements with only a
222: * single statement, unless it's a long statement.
223: *
224: * Forever loops are done with for's, not while's.
225: */
226: for (p = buf; *p != '\0'; ++p)
227: ; /* Do nothing */
228: for (;;)
229: stmt;
230:
231: /*
232: * Parts of a for loop may be left empty. Don't put
233: * declarations inside blocks.
234: */
235: for (; cnt < 15; cnt++) {
236: stmt1;
237: stmt2;
238: }
239:
240: /*
241: * Indentation is an 8 character tab. If you have to wrap a
242: * long statement, put the operator at the end of the line.
243: */
244: while (cnt < 20 && this_variable_name_is_too_long &&
245: ep != NULL)
246: z = a + really + long + statment + that + needs +
247: two + lines + gets + indented + properly +
248: on + the + second + and + subsequent + lines;
249:
250: /* Do not add whitespace at the end of a line, */
251:
252: /*
253: * Closing and opening braces go on the same line as the else.
254: * Don't add braces that aren't necessary except in cases where
255: * there are ambiguity or readability issues.
256: */
257: if (test) {
258: /*
259: * I have a long comment here.
260: */
261: stmt;
262: } else if (bar) {
263: stmt;
264: stmt;
265: } else
266: stmt;
267:
268: /*
269: * No spaces after function names. Commas have a space after them.
270: * No spaces after `(' or `[' or preceding `]' or `)' characters.
271: */
272: error = function(a1, a2);
273: if (error != 0)
274: exit(error);
275:
276: /*
277: * Unary operators don't require spaces, binary operators do.
278: * Don't excessively use parenthesis, but they should be used if
279: * statement is really confusing without them, such as:
280: * a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;
281: */
282: a = ((b->c[0] + ~d == (e || f)) || (g && h)) ? i : (j >> 1);
283: k = !(l & FLAGS);
284:
285: /*
286: * Exits should be 0 on success, and other value on failure.
287: * Avoid obvious comments such as "Exit 0 on success."
288: */
289: exit(0);
290: }
291:
292: /*
293: * The function type should be on a line by itself preceding the
294: * function. The opening brace of the function body should be on a
295: * line by itself.
296: */
297: static char *
298: function(int a1, int a2, float fl, int a4)
299: {
300: /*
301: * When declaring variables in functions declare them sorted
302: * by size; multiple ones per line are okay.
303: *
304: * DO NOT use function calls in initializers.
305: */
306: struct foo three, *four;
307: double five;
308: int *six, seven;
309: char *nine, ten, eleven, twelve;
310:
311: /*
312: * Casts and sizeof's are not followed by a space. NULL is
313: * any pointer type, and doesn't need to be cast, so use NULL
314: * instead of (struct foo *)0 or (struct foo *)NULL. Also,
315: * test pointers against NULL, i.e. use:
316: *
317: * (p = f()) == NULL
318: * not:
319: * !(p = f())
320: *
321: * Don't use '!' for tests unless it's a boolean, e.g. use
322: * "if (*p == '\0')", not "if (!*p)".
323: *
324: * Routines returning void * should not have their return
325: * values cast to any pointer type.
326: *
327: * Values in return statements should NOT be enclosed in
328: * parentheses.
329: */
330: if ((four = malloc(sizeof(struct foo))) == NULL)
331: err(1, NULL);
332: if ((six = (int *)overflow()) == NULL)
333: errx(1, "Number overflowed.");
334: return eight;
335: }
336:
337: static void
338: usage()
339: {
340: /* Insert an empty line if the function has no local variables. */
341:
342: /*
343: * Use printf, not fputs/puts/putchar/whatever, it's faster
344: * and usually cleaner, not to mention avoiding stupid bugs.
345: *
346: * Usage statements should look like the manual pages. Options
347: * w/o operands come first, in alphabetical order inside a
348: * single set of braces. Followed by options with operands,
349: * in alphabetical order, each in braces. Followed by
350: * required arguments in the order they are specified,
351: * followed by optional arguments in the order they are
352: * specified. A bar ('|') separates either/or
353: * options/arguments, and multiple options/arguments which are
354: * specified together are placed in a single set of braces.
355: *
356: * "usage: f [-ade] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\n"
357: * "usage: f [-a | -b] [-c [-de] [-n number]]\n"
358: */
359: (void)fprintf(stderr, "usage: f [-ab]\n");
360: exit(1);
361: }
362: </pre>
363:
364: </td>
365: </tr>
366: <tr>
367: <td id="footer" colspan="2" style="vertical-align: top;">
368: <a href="http://sourceforge.net">
369: <img src="http://sourceforge.net/sflogo.php?group_id=132028&type=1"
370: alt="SourceForge.net Logo" border="0" height="31" width="88"></a><br>
371: Copyright© 2005-2007 Kohsuke Ohtani
372: </td>
373: </tr>
374:
375: </tbody>
376: </table>
377:
378: </div>
379: <div id="bottom"></div>
380:
381: </body>
382: </html>
CVSweb
![[BACK]](/icons/back.gif){kind=icon}
Return to standard.html CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / prex / doc / html / doc