1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
---------------------------------------------------------
Kexi Naming Conventions
These rules apply to Kexi Team developers
There are also guidelines for future naming decissions.
Started: 2003-10-17
Copyright (C) 2003 Kexi Team
Kexi home page: http://www.kexi-project.org/
---------------------------------------------------
1. Namespaces
To simplify class names and make these names shorter, we use namespaces.
1.1. KexiDB namespace
This denotes KexiDB module. All classes from kexidb/ directory are in KexiDB
namespace.KexiDB-compatible database drivers (from kexidb/drivers/
subdirectories are not in this KexiDB namespace.
1.2. KexiWindow ???
#TODO
2. Directories
plugins/<subdirs>
any plugins like Kexi dialogs for table altering, query desinger, etc.;
one subdirectory per plugin; each subdirectory is a KDE module
widgets/<subdirs>
any widgets that are not dependent on core nor kexidb, thus reusable
in other projects; one subdirectory per widget; all subdirectories are linked
together with static compilation to single common library
3rdparty/<subdirs>
any modules that can be considered as external (not necessarily optional)
3. Creating documentation
- Doxygen (www.doxygen.org) is used for generating Kexi developer documentation.
- default target directory of these docs in html format is: doc/html for all sources
and doc/kexidb/html for kexidb-only docs
- one step (..) up from mentioned dirs are places for .doxygen project files used
for docs generating
- Single-line comments are created begginning with: //!
- Multi-line comments are created begginning with /*! or /**
- Style of comments (/*! of /**) for given file should be preserved
Example 3.1: Comments for non-void functions, adding information about parameters:
/*! Displays value of \a x.
\return true if displaying is successfull */
bool display(int x);
Notes for example:
-\return special Doxygen's tag is used to describe that we return
something in the method (\returns will not work for Doxygen!).
-Clause should be started from capital letter and terminated with a dot.
-"\a" special tag should be used before inserting argument names (names are
equal to these from the method's definition) - the names will be therefore
highlighted by Doxygen.
-For more sophisticated methods (with more arguments), you can as well
use \param tag, e.g.:
/*!
\param x horizontal position
\param y vertical position
\param col color of the box
*/
-Methods/functions should be documented in header files (.h), not in implementation
files. This allows easier inspection for users of the source code.
-Comments from implementation files can be turned into
additional documentation, if really needed (when we use "/*!")
and this also will be included to generated docs if Doxygen project has enabled appropriate
option for doing this.
-Classes should be also documented -comments put just as the lines
before "class keyword.
-to add reference to similar or related function, use \sa tag, e.g.:
/*! blablabla
\sa bleble
*/
-to mark a code fragment that someting is TO DO, you can use \todo tag, e.g.:
/*! \todo (js) it is so hard to implement!
*/
-example above shows that adding e.g. own nick inside the brackets what can help
to recognise who marked given fragment.
4. Indentation
4.1 We can use the rule as in the rest of KDE code.
example:
QString objectName(); //wrong
QString objectName(); //ok
rule: dont use tabs between words.
4.2 To avoid many indentation levels, we can use:
void mymethod()
{
if (!something)
return;
if(!something_else && .....)
return
do_something();
}
instead of:
void mymethod()
{
if (something) {
if(something_else && .....) {
do_something;
}
}
}
This is good, because made qt and kde sources readable.
4.3 Indentation within classes declaration
class MyClass {
public:
MyClass();
void method();
protected:
};
ANYWAY: we use indentation.
|
