Table of Contents
- Document your classes easily: use KDOC
- Class source documentation formatting rules
- User lower case filenames
- The class naming convention
- Don't hardcode paths
- Remember our commitment to network transparency
- Class names are prefixed with a K and capitalize each
following word, eg.
KMyCuteType. - Class members begin with a lowercase letter, all subsequent words
begin with caps, eg.
myCuteFunction()
Document your classes easily: use KDOC
KDOC is the KDE defacto standard application for generating documentation for classes directly from their source code. It's very easy to do and many sections of the KDE already use it (including libkde and kfm). Its output is very similar to that of the documentation of Qt and also allows referencing of Qt classes and methods.
Class source documentation formatting rules
This is the javadoc style of formatting:
// The carriage return after the "/**" is required by javadoc, though
// DOC++ handles it's absence ok.
/**
* This is my class. It is a very simple class.
*
* This is the documentation for my class. . Notice that there
* is nothing between this documentation section and the declaration for
* the class.
*
* @short This is the short description for my class
* @author My Name (any string)
* @version 0.1alpha (any string)
* @see anotherClass#anotherMethod
*/
class MyClass : public MyBaseClass
{
public:
// an empty doc tag.
/**
*/
void myMethod();
// a method with more fleshed out documentation
/**
* I am a documented method.
* Build your own class documentation today.
*
* Since these sentences are separated from the rest by atleast
* one blank line, this will be a paragraph by itself.
*
* @see anotherClass#someOtherMethod
* @see aThirdClass
*
* @return a cute value
* @param parA A parameter that isnt used.
* @param parB Another parameter.
*/
int myCuteMethod( int parA, const char *parB );
};
That should get you started, hopefully. Both DOC++ and kdoc allow you to embed HTML or LaTeX into the documentation but this is not normally a good idea as it limits you to a single format of output.
Be careful to make sure that you do not put in structural HTML tags like <HTML> in your documentation; remember that it will be parsed as HTML and may come out all wrong!
More info on the javadoc source documentation format is available at http://java.sun.com/products/jdk/javadoc/writingdoccomments.html
User lower case filenames
Try to use lower-case filenames for all your source files. This makes it easier for other developers to remember what source files to look for when they debug, modify or include your code.
The class naming convention
The KDE class naming convention, as decided, is:
Don't hardcode paths
..not into your makefiles... and especially not into your source. Use theKApplication directory accessors in your source
and the KDE File System Standard.
... QString icondir = kapp->kde_icondir(); ...
KApplication::kdedir() has been removed from the class and
will no longer work.
Remember our commitment to network transparency
We plan to dominate the world using all sorts of lowdown tactics and cunning tricks, one of which is transparent access to network resources. It's a little tricky to program this into your apps yet, but the source for programs like kedit are good starters to understanding how this can be done with kfm's nice async network-transparent IO library. Learn to be a master to kioslave! (see the Dealing with Network Resources tutorial).
