Annotation of prex-old/doc/html/doc/standard.html, Revision 1.1.1.1.2.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"
1.1.1.1.2.1! nbrk 26: style="width: 250px; height: 54px;"></a>
1.1 nbrk 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>
1.1.1.1.2.1! nbrk 46: <td id="doc" style="vertical-align: top;">
1.1 nbrk 47: <h1>Prex Coding Standard</h1>
48:
1.1.1.1.2.1! nbrk 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>
1.1 nbrk 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