koffice/kexi/doc/dev/naming_conventions.txt

---------------------------------------------------------
 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.