You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
138 lines
3.8 KiB
138 lines
3.8 KiB
---------------------------------------------------------
|
|
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.
|