XL CODING STYLE ======================== AN APOLOGY AND WARNING ---------------------- Much of the code in xl does not yet follow this coding style document in every respect. However, new code is expected to conform. Patches to improve the style of existing code are welcome. Please separate these out from functional changes. If it is not feasible to conform fully to the style while patching old code, without doing substantial style reengineering first, we may accept patches which contain nonconformant elements, provided that they don't make the coding style problem worse overall. In this case, the new code should conform to the prevailing style in the area being touched. ERROR HANDLING -------------- Unless, there are good reasons to do otherwise, the following error handling and cleanup paradigm should be used: * All local variables referring to resources which might need cleaning up are declared at the top of the function, and initialised to a sentinel value indicating "nothing allocated". For example, libxl_evgen_disk_eject *evg = NULL; int nullfd = -1; * If the function is to return a libxl error value, `rc' is used to contain the error code, but it is NOT initialised: int rc; * There is only one error cleanup path out of the function. It starts with a label `out:'. That error cleanup path checks for each allocated resource and frees it iff necessary. It then returns rc. For example, out: if (evg) libxl__evdisable_disk_eject(gc, evg); if (nullfd >= 0) close(nullfd); return rc; * Function calls which might fail (ie most function calls) are handled by putting the return/status value into a variable, and then checking it in a separate statement: char *dompath = libxl__xs_get_dompath(gc, bl->domid); if (!dompath) { rc = ERROR_FAIL; goto out; } * If a resource is freed in the main body of the function (for example, in a loop), the corresponding variable has to be reset to the sentinel at the point where it's freed. Whether to use the `out' path for successful returns as well as error returns is a matter of taste and convenience for the specific function. If you reuse the `out' path for successful returns, there may be resources which are to be returned to the caller rather than freed. In that case you have to reset the local variable to `nothing here', to avoid the resource being freed on the out path. That resetting should be done immediately after the resource value is stored at the applicable _r function parameter (or equivalent). Do not test `rc' in the out section, to discover whether to free things. The uses of the single-line formatting in the examples above are permitted exceptions to the usual xl code formatting rules. FORMATTING AND NAMING --------------------- Blatantly copied from qemu and linux with few modifications. 1. Whitespace Of course, the most important aspect in any coding style is whitespace. Crusty old coders who have trouble spotting the glasses on their noses can tell the difference between a tab and eight spaces from a distance of approximately fifteen parsecs. Many a flamewar have been fought and lost on this issue. Xl indents are four spaces. Tabs are never used, except in Makefiles where they have been irreversibly coded into the syntax. Spaces of course are superior to tabs because: - You have just one way to specify whitespace, not two. Ambiguity breeds mistakes. - The confusion surrounding 'use tabs to indent, spaces to justify' is gone. - Tab indents push your code to the right, making your screen seriously unbalanced. - Tabs will be rendered incorrectly on editors who are misconfigured not to use tab stops of eight positions. - Tabs are rendered badly in patches, causing off-by-one errors in almost every line. - It is the xl coding style. Do not leave whitespace dangling off the ends of lines. 2. Line width Lines are limited to 75-80 characters. Rationale: - Some people like to tile their 24" screens with a 6x4 matrix of 80x24 xterms and use vi in all of them. The best way to punish them is to let them keep doing it. - Code and especially patches is much more readable if limited to a sane line length. Eighty is traditional. - It is the xl coding style. 3. Naming C is a Spartan language, and so should your naming be. Unlike Modula-2 and Pascal programmers, C programmers do not use cute names like ThisVariableIsATemporaryCounter. A C programmer would call that variable "tmp", which is much easier to write, and not the least more difficult to understand. HOWEVER, while mixed-case names are frowned upon, descriptive names for global variables are a must. To call a global function "foo" is a shooting offense. GLOBAL variables (to be used only if you _really_ need them) need to have descriptive names, as do global functions. If you have a function that counts the number of active users, you should call that "count_active_users()" or similar, you should _not_ call it "cntusr()". Encoding the type of a function into the name (so-called Hungarian notation) is brain damaged - the compiler knows the types anyway and can check those, and it only confuses the programmer. LOCAL variable names should be short, and to the point. If you have some random integer loop counter, it should probably be called "i". Calling it "loop_counter" is non-productive, if there is no chance of it being mis-understood. Similarly, "tmp" can be just about any type of variable that is used to hold a temporary value. Local variables used to store return values should have descriptive name like "rc" or "ret". Following the same reasoning the label used as exit path should be called "out". Function arguments which are used to return values to the caller should be suffixed `_r' or `_out'. Variables, type names and function names are lower_case_with_underscores. Xl should avoid using libxl_ and libxl__ as prefix for its own function names. 4. Statements Don't put multiple statements on a single line. Don't put multiple assignments on a single line either. Error code paths with an if statement and a goto or a return on the same line are allowed. Examples: if (rc) goto out; if (rc < 0) return; Xl coding style is super simple. Avoid tricky expressions. 5. Block structure Every indented statement is braced, but blocks that contain just one statement may have the braces omitted. To avoid confusion, either all the blocks in an if...else chain have braces, or none of them do. The opening brace is on the line that contains the control flow statement that introduces the new block; the closing brace is on the same line as the else keyword, or on a line by itself if there is no else keyword. Examples: if (a == 5) { printf("a was 5.\n"); } else if (a == 6) { printf("a was 6.\n"); } else { printf("a was something else entirely.\n"); } if (a == 5) printf("a was 5.\n"); An exception is the opening brace for a function; for reasons of tradition and clarity it comes on a line by itself: void a_function(void) { do_something(); } Rationale: a consistent (except for functions...) bracing style reduces ambiguity and avoids needless churn when lines are added or removed. Furthermore, it is the xl coding style.