gCAD CODING STYLE ================= Draft #2 - July 24th. 1999 Iņigo Serna Huge software projects need a common coding style to make sources clearer and easy to read, understand, write and even fix or modify. Moreover, this is mandatory in a project joining people from different countries usually speaking different languages and who only can communicate via Internet. Although each programmer certainly has his own preferred style he surely thinks the best, we are compeled to agree in a basic style. Thus, this paper intends to create a basic common ground to facilitate the writing of code for the gCAD project. [ Author's NOTE: Though most of next considerations are product of some time of thinking and reflection, there are other things which are obviously my personal preferences, mainly the 'Code Indentation' section. I've spent some time reading several sources for coding style and these are the results I've taken. Nevertheless, this is just an approach, we have to read, discuss, add, delete, modify and agree in a standard. But finally we have to adopt it when writing new code, this is the final and surely more difficult task. It will be very difficult (I'm afraid impossible) to adopt it in some of the already written code (such as Varkon's Database and Geometric Modules), but all the new code should follow it. Finally I'd suggest mantaining the style when modifying existing files for simplicity reasons, i.e., when adding some code to an existing file, use the same indentation style. ] 1. GENERAL ---------- Use '-Wall' flag when compiling sources to get all the warnings (and errors, of course) your code generates. Then try to fix them. Maybe they are not critical but it doesn't look nice, isn't it? ;-) When possible, try to avoid the use of 'goto' clauses. 2. MODULES AND FILES -------------------- gCAD is splitted into independant modules, each module has its own directory where their sources reside. The name of the directory is composed by two capital letters indicating its purpose (GE -> GEometric, UI -> User Interface, DB -> DataBase, GR -> GRaphic, ...). Each module has a 'configure' script which supplies information about the libraries and programs needed to properly compile the module. The modules are compiled as shared libraries (***** FIXME: as static libraries by now *****). In each module directory, there must exist next files: AUTHORS, README, ChangeLog and TODO, which have to be filled properly. The sources for a module must reside in that directory (***** FIXME: or with include/src structure? Have we agreed on it yet? *****). The modules can also contain more subdirs for other purposes, such as 'doc', 'data', etc. Sources files names must be lower-case. It's a good practice to split the code of a module into several logical files containing common information (f.e., in UI module: menu.c, toolbar.c, gl.c, etc.). Thus we achieve serveral advantages, like avoiding very large files that could make compiling with optimitation a pain, an easier understanding of code or easier finding of functions. Finally, each module must have a header file called 'module.h' (ui.h, db.h, ...) containing all the public functions and datatypes to be called from other modules. 3. FUNCTIONS AND DATATYPES -------------------------- As stated above, each module has some functions and datatypes that have to be exported to be accesible from other modules. All this public information must be declared in a header file called 'module.h', where 'module' is the abbreviation (2 letters) of the module, in lower-case. I'll explain next points with some examples where you will be able to understand easily the proposed standard: * Public Functions: moduleabbrev_object_action_parameters (...); The name of the module is abbreviated with the 2 lowercased significant letters (those which forms module directory name). The different fields are separated by '_' characters Examples: GePlane* ge_plane_new_3pt (GEPoint *p1, ...); A GEometric module function that creates a new plane object from 3 points. It returns a pointer to the new plane. void ui_command_inserttext (gboolean color, gchar *text); A User Interface function that writes a text in the command-text widget. * Public DataTypes: PfxObject[Moreinfo] The prefix is formed by the 2 letters of the module, first as capital letter and the second in lowercase. Next the object name, with the first character in capital letter, next in lowercase. Examples: GePlane - A Plane for the GEometric module. DbLayer - A Layer in the DataBase module. ExCommandType - The Type of a Command for EXecute module. Basically, this is the same style GNOME and Gtk+ APIs use. The parameters sequence inside functions calls are that first should appear in, and then out parameters. Also, functions should return 0 if all worked well and -1 (or similar value) in case of error. When possible, it's better to use #define's instead of hardcoding values along the code. This will facilitate bugs fixing and code reading. 4. CODE INDENTATION ------------------- I personnaly use 4-spaces tabs. Next there are some examples of code I write: * functions: void foo_function (int a, int b, int c, char* d) { struct time_t* t; int num, i; ... } * if-else, switch-case, while, ... ... if (a == 1) { b = 0; ... } else if (a = 3) { switch (b) { case ON: c = 3; break; case OFF: ... default: c = 0; break; } c -= b; } else while (b < 200) { b *= 2; i++; } ... (***** FIXME: other ideas and suggestions? *****) 5. COMMENTS ----------- As this is a project with people with different native languages, the English has been chosen as the common language, so the comments must be written in this language. The comments are included inside the /* and */ pair, the // C++ comment style is not allowed. The comments for public functions and datatypes must keep a concrete format, the same GNOME and Gtk+ use, based on SGML DocBook, which allows an easy generation of API reference documentation in HTML, PostScript, etc. (***** FIXME: Do we agree? Who know what the format is? *****) 6. MORE STANDARDS ----------------- * GNOME Coding Style Guide WhitePaper: http://www.gnome.org/white-papers/guidelines * Linux Kernel Coding Style: /usr/src/linux/Documentation/CodingStyle * GNU Standards: Type 'info standards' in your linux box shell.