diff options
Diffstat (limited to 'kexi/doc/dev/naming_conventions.txt')
| -rw-r--r-- | kexi/doc/dev/naming_conventions.txt | 137 |
1 files changed, 137 insertions, 0 deletions
diff --git a/kexi/doc/dev/naming_conventions.txt b/kexi/doc/dev/naming_conventions.txt new file mode 100644 index 00000000..8d34f97a --- /dev/null +++ b/kexi/doc/dev/naming_conventions.txt @@ -0,0 +1,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. |