OBC Style Guide Revision Info July 31, 2003 - Final version 1 added the parameters for the indent tool July 22, 2003 - Draft version 2 added details on spacing convention added details on capitalization added details on indentation June 30, 2003 - Draft version 1 Introduction This document is a short guide to the preferred style for code being submitted to or maintained within the OnBoardC project. The project is currently found at the SourceForge site (http://onboardc.sourceforge.net) and also has a discussion group on Yahoo (http://groups.yahoo.com/group/onboardc/). Indentation & Spacing In most other style guides, indentation has been suggested at 8 characters. While this is a good suggestion when editing on a desktop, the hope is that one day OnBoardC development will be taking place on the Palm itself. With that goal in mind, indentation should be set at 4 characters. This will allow for more text to be visible on the screen, and minimize the wasted screen real estate. As well, indentation will be 4 spaces, rather than one tab character. This is to ensure that the code will look the same regardless of the editor being used. To aid in clarity, the following space guidelines should also be followed. There should be one space between operators and parameters in each statement. In function declarations, there should be one space after each comma of the argument list. Additional blank lines should only exist between function bodies, or to break up logical sections of code, such as the global declarations from the macro definitions, etc. Capitalization Macros and constants should be capitalized, to distinguish them immediately from regular variables. For function names, the usual convention in C is to start with a lowercase letter, then allow mixed-case after that. The usual convention in the Palm API is to start with a capital letter, and then allow mixed-case after that. Because of this discrepancy, capitalization will not be proscribed for function names. As long as the capitalization style used does not result in a function name of all capital letters, any style will be accepted. Braces Again we wish to minimize wasted screen space, but not at the expense of clarity. In most cases, opening braces will be placed at the end of the line, rather than on the following line. Closing braces will be placed on a line by itself, lining up with the opening line in terms of indent level. E.g. if (x is true) { do_something(); do_somethingelse(); } One special case is for function declarations. In these cases, it is more important to clearly identify such as a function, rather than as some other statement. To this end, the opening brace will be on a line by itself, for example: int some_function(int x) { do_something(x); return x; } Another special case is when the closing brace is part of a more complex or compound statement. In these cases, to save screen space, the closing brace will begin the succeeding line of the compound statement. E.g. do { do_something(); } while (condition); or if (something == something_else) { do_something(); } else if (x > y) { do_something_else(); } else { do_nothing(); } Comments Comments should be short and sweet whenever possible. Preferably, the code should be written so that it is self-explanitory. Comments shouldn't tell you how something is being done, but rather what is being done, and perhaps why. Comments explaining functions should be in a block format, for example: /* This is a block comment. * You just enter your text * here. */ If a comment is appropriate within a function, then it should be indented to the same level as the code. E.g. if (condition) { /* This is a shorter comment. */ do_something(); } Very short comments can be inlined with the code. E.g. if (a == 2) { return(TRUE); /* special case */ } else { return(isprime(a)); /* works only for odd a */ } Header Files Header files should not be nested. To avoid this, use of #define is suggested. E.g. #ifndef HEADERFILE #define HEADERFILE . . . header file code . . . #endif Declarations The various declarations at the top of a source code file should, whenever possible, follow this suggested layout: - file comments - "#include" declarations - "typedef" and "enum" declarations - "#define" declarations - global variables and "struct" declarations - any function declarations - actual function source code This order should provide for the most clear and logical progression of coding within the actual source code files. In certain circumstances, it is either easier, or more clear, when declarations are done nearer to the code that actually requires it. In these cases, these suggestions should be summarily ignored and go with your own style. Functions Functions should follow all of the above rules, whenever possible. They should begin with a short comment describing it's purpose, if it is not clear from the code. The function declaration should be placed on one line, with the opening brace on a line by itself, following. If the parameter list does not fit within one line, it should be indented to a level appropriate to have it match up with the parameters from the previous line. For example: /* * This is a function example. */ int some_func(int param1, int param2, char param3, char param3) { do_something; /* If the previous worked, do this */ do_something_else(); } Indent Tool On UNIX, or UNIX-ish, operating systems, there is a program called indent. This tool can be used to apply style rules to a source code file. It is available on UNIX, Linux, the Cygwin tools for Windows, and several other places. The following commandline will apply the above style to your source files: indent -kr -cdw -nut -sob There is one major caveat, however. If you have inline assembler code, you should wrap those sections in indent control commands. This will turn off indent processing, as this seems to mess this code up. For example, you would /* *INDENT-OFF* */ asm some_func() { asm code goes here } /* *INDENT-ON */ This way indent will pass over your assembler code and not mess it up. References The following were references used in writing this style guide: - Annotated Indian Hill Style Guide http://www.chris-lott.org/resources/cstyle/indhill-annot.html - GNU Coding Standards http://www.chris-lott.org/resources/cstyle/gnu-coding-std.txt - Linux Kernel Coding Style http://www.purists.org/linux/ - K&R C Programming