WebSVN – gelsvn – Diff – /trunk/doc/CodingConventions.txt


Andreas Bærentzen, 
December 2001
 
----------------------------------------------------------------------
CODING CONVENTIONS
----------------------------------------------------------------------
 
Coding conventions are very important if the source code is to remain
legible and tidy. Very strict conventions, however, will require too
much work of the programmer, and (if the programmer is myself) he will 
start to ignore some of the conventions in order to do things more
quickly, and then the card house topples.
 
Nothing that imposes too much work should be made a coding
convention. For instance, a standard comment before each function
definition sounds like a good idea, but even with a template, it is
cumbersome to add and maintain these chunks of text, so I choose to
omit them. However, Doxygen comments are added whereever I get around to it.
 
The philosophy behind the conventions below is that they should simply 
be standard ways of doing what a programmer does anyway and that they
should add only very little extra work.
 
USE OF CASE AND SPECIAL CHARACTERS
------------------------------
 
* Abbreviations are used only where the names would otherwise be
ludicrously long.
 
* Names of constants are all uppercase letters. Underscores are used to
combine words, e.g. `MAX_LEVEL'
 
* Names of classes and other new types are in lower case but
inter-capitalized, e.g. `class MyClass'
 
* The names of functions are lower case. Words are combined with
underscores, e.g. `int get_max()'
 
FUNCTION NAMING
------------------------------
 
* Words used
 
The words `get' and `set' are used in the names of functions that
assigns or retrieves the value of some state variable in a class.
 
E.g.
 
get_level
set_level
 
The words `find', `remove', `insert' are used in the names of
functions that access a database.
 
E.g.
 
find_node
remove_node
insert_node
 
The word `create' is used in the name of a function that creates and
returns a member of a class, e.g.
 
create_inquirer
 
The word `inquirer' is used in the names of functions that access
data structures. E.g.
 
OctreeInquirer
 
COMMENTING
------------------------------
 
* Comments are used where appropriate. DOC++ comments are used 
for all class members in .h files. There are no comments used
purely for aestethical or ``typographical'' reasons.
...
 
At some point I may add a standard file header. Could contain CVS
information perhaps.
 
FUNCTION ARGUMENTS
------------------------------
 
* Constructor arguments. If a class X contains a variable y that is
initialized in the contructor of X, then the argument to the
constructor should be _y, that is
 
X::X(_y): y(_y) {}
 
* Usually a function takes arguments that are constant and ``call by
reference'' arguments that may be modified. The constant arguments
should come first, then the modifiable. E.g.
 
        foo(const MyClass&, int, float&);
 
has two constant arguments followed by a float which is passed by
reference.
 
FILE (NAMING) CONVENTIONS
------------------------------
 
* All classes that are not auxiliary (i.e. used only by one particular
other class) have a header file of their own. 
 
* The name of the header file is that of the class + `.h'
 
* All non-auxiliary classes with one or more functions that are not
inline have a definition file of their own.
 
* The name of the definition file is that of the class + `.cpp'
 
* The #define <macro> in the include guard uses the name of the
  namespace followed by the name of the file - capitalized and with dot
  replaced by underscore.	This string is also preceeded and followed by
	two underscores. For instance,
 
 
 
#ifndef __CGLA__ARITHVECFLOAT_H__
#define __CGLA__ARITHVECFLOAT_H__
 
... code ....
 
#endif
 
  Not all code adheres to this convention yet.
 
 

Subversion Repositories gelsvn

(root)/trunk/doc/CodingConventions.txt – Rev 2 → 136

Rev 2		Rev 136
1	`Andreas Bærentzen,`	1	`Andreas Bærentzen,`
2	`December 2001`	2	`December 2001`
3		3
4	`----------------------------------------------------------------------`	4	`----------------------------------------------------------------------`
5	`CODING CONVENTIONS`	5	`CODING CONVENTIONS`
6	`----------------------------------------------------------------------`	6	`----------------------------------------------------------------------`
7		7
8	`Coding conventions are very important if the source code is to remain`	8	`Coding conventions are very important if the source code is to remain`
9	`legible and tidy. Very strict conventions, however, will require too`	9	`legible and tidy. Very strict conventions, however, will require too`
10	`much work of the programmer, and (if the programmer is myself) he will`	10	`much work of the programmer, and (if the programmer is myself) he will`
11	`start to ignore some of the conventions in order to do things more`	11	`start to ignore some of the conventions in order to do things more`
12	`quickly, and then the card house topples.`	12	`quickly, and then the card house topples.`
13		13
14	`Nothing that imposes too much work should be made a coding`	14	`Nothing that imposes too much work should be made a coding`
15	`convention. For instance, a standard comment before each function`	15	`convention. For instance, a standard comment before each function`
16	`definition sounds like a good idea, but even with a template, it is`	16	`definition sounds like a good idea, but even with a template, it is`
17	`cumbersome to add and maintain these chunks of text, so I choose to`	17	`cumbersome to add and maintain these chunks of text, so I choose to`
18	`omit them.`	18	`omit them. However, Doxygen comments are added whereever I get around to it.`
19		19
20	`The philosophy behind the conventions below is that they should simply`	20	`The philosophy behind the conventions below is that they should simply`
21	`be standard ways of doing what a programmer does anyway and that they`	21	`be standard ways of doing what a programmer does anyway and that they`
22	`should add only very little extra work.`	22	`should add only very little extra work.`
23		23
24	`USE OF CASE AND SPECIAL CHARACTERS`	24	`USE OF CASE AND SPECIAL CHARACTERS`
25	`------------------------------`	25	`------------------------------`
26		26
27	`* Abbreviations are used only where the names would otherwise be`	27	`* Abbreviations are used only where the names would otherwise be`
28	`ludicrously long.`	28	`ludicrously long.`
29		29
30	`* Names of constants are all uppercase letters. Underscores are used to`	30	`* Names of constants are all uppercase letters. Underscores are used to`
31	combine words, e.g. `MAX_LEVEL'	31	combine words, e.g. `MAX_LEVEL'
32		32
33	`* Names of classes and other new types are in lower case but`	33	`* Names of classes and other new types are in lower case but`
34	inter-capitalized, e.g. `class BoneMachine'	34	inter-capitalized, e.g. `class MyClass'
35		35
36	`* The names of functions are lower case. Words are combined with`	36	`* The names of functions are lower case. Words are combined with`
37	underscores, e.g. `int get_max()'	37	underscores, e.g. `int get_max()'
38		38
39	`FUNCTION NAMING`	39	`FUNCTION NAMING`
40	`------------------------------`	40	`------------------------------`
41		41
42	`* Words used`	42	`* Words used`
43		43
44	The words `get' and `set' are used in the names of functions that	44	The words `get' and `set' are used in the names of functions that
45	`assigns or retrieves the value of some state variable in a class.`	45	`assigns or retrieves the value of some state variable in a class.`
46		46
47	`E.g.`	47	`E.g.`
48		48
49	`get_level`	49	`get_level`
50	`set_level`	50	`set_level`
51		51
52	The words `find', `remove', `insert' are used in the names of	52	The words `find', `remove', `insert' are used in the names of
53	`functions that access a database.`	53	`functions that access a database.`
54		54
55	`E.g.`	55	`E.g.`
56		56
57	`find_node`	57	`find_node`
58	`remove_node`	58	`remove_node`
59	`insert_node`	59	`insert_node`
60		60
61	The word `create' is used in the name of a function that creates and	61	The word `create' is used in the name of a function that creates and
62	`returns a member of a class, e.g.`	62	`returns a member of a class, e.g.`
63		63
64	`create_inquirer`	64	`create_inquirer`
65		65
66	The word `inquirer' is used in the names of functions that access	66	The word `inquirer' is used in the names of functions that access
67	`data structures. E.g.`	67	`data structures. E.g.`
68		68
69	`OctreeInquirer`	69	`OctreeInquirer`
70		70
71	`COMMENTING`	71	`COMMENTING`
72	`------------------------------`	72	`------------------------------`
73		73
74	`* Comments are used where appropriate. DOC++ comments are used`	74	`* Comments are used where appropriate. DOC++ comments are used`
75	`for all class members in .h files. There are no comments used`	75	`for all class members in .h files. There are no comments used`
76	purely for aestethical or ``typographical'' reasons.	76	purely for aestethical or ``typographical'' reasons.
77	`...`	77	`...`
78		78
79	`At some point I may add a standard file header. Could contain CVS`	79	`At some point I may add a standard file header. Could contain CVS`
80	`information perhaps.`	80	`information perhaps.`
81		81
82	`FUNCTION ARGUMENTS`	82	`FUNCTION ARGUMENTS`
83	`------------------------------`	83	`------------------------------`
84		84
85	`* Constructor arguments. If a class X contains a variable y that is`	85	`* Constructor arguments. If a class X contains a variable y that is`
86	`initialized in the contructor of X, then the argument to the`	86	`initialized in the contructor of X, then the argument to the`
87	`constructor should be _y, that is`	87	`constructor should be _y, that is`
88		88
89	`X::X(_y): y(_y) {}`	89	`X::X(_y): y(_y) {}`
90		90
91	* Usually a function takes arguments that are constant and ``call by	91	* Usually a function takes arguments that are constant and ``call by
92	`reference'' arguments that may be modified. The constant arguments`	92	`reference'' arguments that may be modified. The constant arguments`
93	`should come first, then the modifiable. E.g.`	93	`should come first, then the modifiable. E.g.`
94		94
95	`foo(const MyClass&, int, float&);`	95	`foo(const MyClass&, int, float&);`
96		96
97	`has two constant arguments followed by a float which is passed by`	97	`has two constant arguments followed by a float which is passed by`
98	`reference.`	98	`reference.`
99		99
100	`FILE (NAMING) CONVENTIONS`	100	`FILE (NAMING) CONVENTIONS`
101	`------------------------------`	101	`------------------------------`
102		102
103	`* All classes that are not auxiliary (i.e. used only by one particular`	103	`* All classes that are not auxiliary (i.e. used only by one particular`
104	`other class) have a header file of their own.`	104	`other class) have a header file of their own.`
105		105
106	* The name of the header file is that of the class + `.h'	106	* The name of the header file is that of the class + `.h'
107		107
108	`* All non-auxiliary classes with one or more functions that are not`	108	`* All non-auxiliary classes with one or more functions that are not`
109	`inline have a definition file of their own.`	109	`inline have a definition file of their own.`
110		110
111	* The name of the definition file is that of the class + `.cc'	111	* The name of the definition file is that of the class + `.cpp'
112		112
113	`* The #define <macro> in the include guard uses the name of the file -`	113	`* The #define <macro> in the include guard uses the name of the`
-		114	`namespace followed by the name of the file - capitalized and with dot`
114	`capitalized and with dot replaced by underscore. The macro name is`	115	`replaced by underscore. This string is also preceeded and followed by`
115	`preceded by two underscores`	116	`two underscores. For instance,`
116		117
117	`E.g.`	-
118		-
119	`#ifndef __BONEMACHINE_H`	118	`#ifndef __CGLA__ARITHVECFLOAT_H__`
120	`#define __BONEMACHINE_H`	119	`#define __CGLA__ARITHVECFLOAT_H__`
121		120
122	`... code ....`	121	`... code ....`
123		122
124	`#endif`	123	`#endif`
125		124
-		125	`Not all code adheres to this convention yet.`
-		126
126		127