154 lines
4.9 KiB
Plaintext
154 lines
4.9 KiB
Plaintext
______________________________________________________________________
|
|
|
|
Goldware Source Style Guide
|
|
By Odinn Sorensen
|
|
14. November 1998
|
|
|
|
______________________________________________________________________
|
|
|
|
Please learn from this example:
|
|
|
|
=== Cut ===
|
|
// ------------------------------------------------------------------
|
|
// This is an example function
|
|
|
|
int function(char* d, char* s, int i, int j) {
|
|
|
|
if(not(i==2 or j<5) xor (i>5 and j<32)) {
|
|
switch(i) {
|
|
case 1:
|
|
printf("1\n");
|
|
break;
|
|
default:
|
|
printf("whatever\n");
|
|
}
|
|
}
|
|
else {
|
|
for(int n=0; n<i; n++) {
|
|
// copy something
|
|
*d++ = *s++;
|
|
}
|
|
}
|
|
|
|
switch(*s) {
|
|
case '\0': printf("nul-terminated\n"); break;
|
|
case ' ': printf("terminated with a space\n"); break;
|
|
}
|
|
|
|
return i;
|
|
}
|
|
|
|
|
|
// ------------------------------------------------------------------
|
|
=== Cut ===
|
|
|
|
Lessons:
|
|
|
|
* Indentation is two spaces per level. Tabs are NOT allowed!
|
|
|
|
* No space between keyword/function name and left parenthesis.
|
|
|
|
* Opening brace is at the end of the line.
|
|
|
|
* Closing brace is lined up at the same level as the line with the
|
|
opening brace.
|
|
|
|
* In a switch statement, 'case' is indented, and the content of a case
|
|
is indented further. A compact form of switch is allowed for short
|
|
cases - arrange it so that each case with content is on one line,
|
|
and place spaces so that the whole thing is neatly columnized.
|
|
|
|
* C++ comment style is used.
|
|
|
|
* Comment lines that separate functions are 70 chars wide.
|
|
|
|
* There is one empty line between the last comment line describing a
|
|
function and the beginning of the function.
|
|
|
|
* There are two empty lines between the closing brace for a function
|
|
and the following separating comment line.
|
|
|
|
* At some places in expressions there are still AND,OR,NOT used. If
|
|
you're just editing places, replace them by and,or,not. Please do
|
|
not use &&,||,! etc.! We prefer readable source and do not like
|
|
symbols at places where we can use human readable text. Note that
|
|
the lowercase variants are defined by ANSI C++ standard.
|
|
|
|
Other lessons:
|
|
|
|
* Avoid using global variables.
|
|
|
|
* Avoid using static variables.
|
|
|
|
* Avoid using fixed length char buffers.
|
|
|
|
* Use the gstring class for strings and the gvector class for
|
|
STL-style vectors. But DO NOT use them in any global variable,
|
|
unless the global variable is a pointer.
|
|
|
|
* Don't use STL. Sorry :-(
|
|
|
|
* Don't use MixedCase for variable, class or function names. Use
|
|
lowercasealltheway or lowercase_with_underscores if you must.
|
|
|
|
* Use 8.3 MS-DOS filenames for source files and other files that are
|
|
part of the build system, at least until we have some program or
|
|
script that can convert from long filenames to short, or we decide
|
|
to drop 16-bit MS-DOS support entirely.
|
|
|
|
|
|
The real world:
|
|
|
|
GoldED and the Goldware Library has been developed over many years,
|
|
and has gone through several code restylings over the years. This
|
|
means that the rules above are broken in many places around the code,
|
|
and sometimes the rules are bent a bit on purpose to make the code
|
|
more readable or easier to debug.
|
|
|
|
But try to stay close to the rules anyway.
|
|
|
|
Browse the code and get a feel for the layout.
|
|
|
|
|
|
If you are in doubt about where to place the source for new
|
|
functionality, please place as much as possible in the library, in the
|
|
form of generalized functions and/or classes. This way more people can
|
|
benefit from it (since it will be LGPL, not GPL by default), and the
|
|
functionality can be used in both the old 3.x code and the new 4.x
|
|
code with a minimum of duplication and effort.
|
|
|
|
|
|
When you make fixes or add functionality, please check carefully that
|
|
your modification don't have unexpected side-effects. This is
|
|
particularly the case with the GoldED 3.x code and gmb3, which
|
|
unfortunatly still has a legacy base of global tangled spaghetti code.
|
|
In fact, if you are messing with almost any aspect of the message
|
|
related code, it is more than 50% certain that the first fix you make
|
|
has entirely unexpected sideeffects that perhaps is not even seen
|
|
until someone else uses a feature that you never use.
|
|
|
|
|
|
If you have made some modifications and want to contribute them to the
|
|
community, please use "diff -c" (context format) to generate the patch
|
|
file.
|
|
|
|
Before sending in patches to me or another member of the core
|
|
developer team, TEST TEST TEST and TEST AGAIN. Preferrably the patch
|
|
(or patched version) should be tested by several other users so that
|
|
you can be reasonably sure that it's okay.
|
|
|
|
|
|
It is very recommended to use CVS and checkout the source from the
|
|
official Goldware CVS server (when it becomes available). It saves you
|
|
and us for much headache when merging the patches into the main source
|
|
and you want to update your checkout with the latest checkins to the
|
|
official source. Get your CVS client from www.cyclic.com.
|
|
|
|
|
|
Enjoy! :-)
|
|
|
|
Odinn Sorensen
|
|
|
|
______________________________________________________________________
|
|
|