$VER OpenBOOPSI Project Style Guide 1.1 (4.5.99) OpenBOOPSI Project Style Guide ---- 0. SUMMARY 1. Introduction 2. Comments 2.1 General Rules 2.2 Language 2.3 Single line comments 2.4 Multi line comments 3. Blank Spaces 3.1 Tabs 3.2 Spaces 3.3 Empty lines 4. Naming Conventions 4.1 General Rules 4.2 Functions 4.3 Variables 1. INTRODUCTION This is a brief guide on recommended source code formatting style for the OpenBOOPSI Project classes. Every source file added to this project should conform as close as possible to the rules given in this document to mantain consistency within the source tree. It might happen that you're already used to a different coding style. Yes, we all understand well that changing your style can be frustrating for any programmer. But the need to keep the source code style consistent is more important than each one's habits. No one will blame you if you don't strictly follow these guidelines, but we will be glad if you do. 2. COMMENTS 2.1 GENERAL RULES Comment as much as you can. Other programmers will read your sources and since most of them will have different knowledge of Amiga programming and/or different ways to do a certain thing they may not understand the purpose or the inner working of some of your code, so try to explain what you are doing. Obviously avoid comments such as "now open a window" right above a OpenWindow() function call. 2.2 LANGUAGE Comments must be written in english. 2.3 SINGLE LINE COMMENTS Single line comments should follow the ANSI C syntax, i.e. using the "/* */" construct. C++ comments must not be used because not all C compilers do support them. 2.4 MULTI LINE COMMENTS Comments spanning over multiple lines should be formatted this way: /* This is a very very very * very very long comment! */ 3. BLANK SPACES 3.1 TABS Tabs are four spaces wide. 3.2 SPACES There should be a space after commas. There should never be a space after a * when it's used with pointers, e.g.: ULONG *pointer = NULL; *pointer = 45 * y; There should be a blank space around operators, e.g.: var1 + var2; var1 & var2; etc. the only exceptions are prefix and postfix ++ and -- operators, i.e.: var--; ++var; Before a parenthesis there should never be blank spaces if it follow a keyword or a function name. e.g. if() /* good */ DoMethod(); /* also good */ while () /* wrong! */ yourfunction (); /* also wrong! */ 3.3 EMPTY LINES After the #include block and after the #define one there should be two empty lines. Between the declaration of the global variables and the beginning of the code there should be two empty lines. Between the end of a function and the next one there should be three empty lines. Any code block enclosed in braces should be preceded by an empty line. An open brace should be on a line by itself. After a closing brace there should be one empty line, except when another closing brace follows. e.g. if(z == 1) { z++; } y += z + 3; if(y > 8) { f = do_some_stuff(); if(f == TRUE) { printf("ok!\n"); } } /* the following is wrong! */ if(y==1) { z++; } y+=z +3; if (y >8) { etc. } 4. NAMING CONVENTIONS 4.3 GENERAL RULES Everything related to the classes (methods, functions, etc.) should have a prefix (two or three letter maximum) that recalls the name of the class. i.e. if your class is called "BananaSplit" its methods should be called something like BSM_SHAKE, its attributes should look like BSA_SugarSpuns, etc. 4.2 FUNCTIONS Method functions should obviously follow the general rule and have the above mentioned prefix, e.g.: BS_GoActive(); Function names should have the first letters of each word forming their names capitalized, like system's one. e.g.: MyWonderfulFunction() 4.3 VARIABLES Variables name must be in english and must have a meaning! Please avoid names such as "foobar" or "dummy"! We hate them! Some examples: struct Window *win; /* these are good */ ULONG result; struct BitMap *dummy1; /* these are wrong! */ struct RastPort *dummy2; Names of local variables should be all in lowercase. Global variables should have their initials uppercase.