<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/2002/REC-xhtml1-20020801/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>Recommanded conventsions in KDE libraries</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link rel="stylesheet" media="screen" type="text/css" title="Default Layout" href="http://developer.kde.org/media/styles/standard.css" />
<style type="text/css" >
pre { background-color: #F6F2FF; padding: 1ex; color: black;}
.comment { color:#555; }
</style>
</head>
<body id="developerkdeorg" >
<div id="content">
<h1>KDE library code guidelines</h1>
<h2>Introduction</h2>
<p>This document show some of the recommanded conventions that should be applied in the KDE libraries. (Not applications)<br/>
Respecting them helps to make a consistant API, but also may help to maintains the libraries later.<br/>
While theses conventions are not immutable, they are importent guidelines, and should be respected unless you have really good reason.</p>
<p>As introduction, you could read the document <a href="http://doc.trolltech.com/qq/qq13-apis.html">Designing Qt-Style C++ APIs</a></p>
<h2>Naming conventions</h2>
<p>In KDE, we follow almost the same naming convention than in Qt</p>
<p>Class names starts with a capital <code>K</code>. The rest is in camel case. Function names starts with a lower case, but the first letter of each successive word is capitalized.</p>
<p>Unless dealing with central libraries (kdecore, kdeui), classes should be in the library namespace.
In that case, it is the namespace which starts with <code>K</code> and the classes inside may not start with it.
New libraries should choose their namespace.</p>
<p>The prefix '<code>set</code>' is used for setter, but <b>not</b> the prefix '<code>get</code>' for accssessor. Accssessors are simply named with the name of the property they access.
The exception is for accssessor of a boolean which may start with the prefix '<code>is</code>' <br/>
<em>private slots</em> may start with the prefix <code>slot</code>, thought it's not required, depending the context.</p>
<p>Acronyms are lowercased too. Example: <code>KUrl</code> instead of <code>KURL</code> ; <code>isNssEnabled</code> instead of <code>isNSSEnabled</code> </p>
<p>Accessor should usually be <code>const</code>.</p>
<p>This example shows some possible functions names</p>
<pre>
<b class="keyword">public:</b>
void setColor( const QColor& c);
QColor color() const;
void setDirty( bool b );
bool isDirty() const;
<b class="keyword">private Q_SLOTS:</b>
void slotParentChanged();
</pre>
<p>Make one public class par <code>.h</code> file. Add the <code>_EXPORT</code> macro related to the library they are in.</p>
<p>Private class should be declared in a the <code>.cpp</code> file, or in a <code>_p.h</code> file</p>
<h2>D-Pointers</h2>
<p>In order to maintain easily binary compatibility, there shouldn't be private members in a public class.</p>
<p>For more information about binary compatibility, read <a href="http://developer.kde.org/documentation/other/binarycompatibility.html">Binary Compatibility Issues With C++</a>.</p>
<p>By convention, the private class will be called <code>Private</code> and will be a in the class definition.</p>
<pre>
<b class="keyword">class</b> KFoo
{
<b class="keyword">public:</b>
<i class="comment">/* public members */</i>
<b class="keyword">private:</b>
<b class="keyword">class</b> Private;
Private * const d;
};
</pre>
<pre>
<b class="keyword">class</b> KFoo::Private
{
<b class="keyword">public:</b>
int someInteger;
}
KFoo::KFoo() : d(new Private)
{
<i class="comment">/* ... */</i>
}
KFoo::~KFoo()
{
<b class="keyword">delete</b> d;
}
</pre>
<p>Notice that The member <code>d</code> is <b><code>const</code></b> to avoid to modify it by mistake.</p>
<p>If you are implementing an implicit shared class, you should consider using <code>QSharedData</code> and <code>QSharedDataPointer</code> for <code>d</code>.<br/>
Use <code>QAtomic</code> for reference counting. Don't try to implement your own refcounting with integers.</p>
<p>Sometimes, complex code may be moved to a member method of the class Private itself. That may give the compiler an extra register to optimize the code,
since you won't be using "d" all the time.</p>
<h2>Flags</h2>
<p>We should try to avoid to have meaningless booleans parameters in functions.</p>
<p>This is an example of bad boolean argument</p>
<p>
<code>static QString KApplication::makeStdCaption( const QString &userCaption,
bool withAppName = true, bool modified = false );</code>
</p>
<p>Because when you read it in a real code, you can't know easily the signification of them</p>
<p>
<code>window->setCaption( KApplication::makeStdCaption( "Document Foo" , true , true ) );</code>
</p>
<p>The solution is to use flags parameter, using <a href="http://doc.trolltech.com/4.1/qflags.html">QFLags</a>.
If the options only apply to one function, call the enum <code>FunctionNameOption</code> and the QFlags typedef <code>FunctionNameOptions</code>. Do that even if there is only one option, this will allow to add more option after and keep
the binary compatibility.</p>
<p>So a better API would be:</p>
<pre>
<b class="keyword">class</b> KApplication
{
<b class="keyword">public:</b>
<i class="comment">/* [...] */</i>
<b class="keyword">enum</b> MakeStandartCaptionOption
{
<i class="comment">/**
* Indicates that the method shall include the application
*/</i>
WithApplicationName = 0x01,
<i class="comment">/**
* If set, a 'modified' sign will be included in the returned string.
*/</i>
Modified = 0x02
};
Q_DECLARE_FLAGS( MakeStandartCaptionOptions, MakeStandartCaptionOption)
<i class="comment">/**
* Builds a caption using a standard layout.
*
* @param userCaption The caption string you want to display
* @param options a set of flags from MakeStandartCaptionOption
*/</i>
static QString makeStandartCaption( const QString& userCaption,
const MakeStandartCaptionOption& options = WithApplicationName );
<i class="comment">/* [...] */</i>
};
Q_DECLARE_OPERATORS_FOR_FLAGS(KApplication::MakeStandartCaptionOptions)
</pre>
<h2>Const references</h2>
<p>Each object parameter that are not basic types (<code>int, float, bool, enum, </code> or pointers) should be passed by constent reference.
This is faster, because it is not required to do a copy of the object. Do that even for object that are already implicitly shared, like QString</p>
<pre>
QString myMethod( const QString& foo, const QPixmap& bar, int number);
</pre>
<h2>Signals and slots</h2>
<p>In the libraries, use <code><b class="keyword">Q_SIGNALS:</b></code> and <code><b class="keyword">Q_SLOTS:</b></code> macro instead of <code>signals:</code> and <code>slots:</code> <br/>
They are syntax equivalent.
They Should be used to avoid conflict with <a href="http://www.boost.org/">boost</a> signals, and with python's use of "slots" in its headers.</p>
<h2>Explicit constructor</h2>
<p>For each constructor, check if you should make them <code><b class="keyword">explicit</b></code> in order to minimize wrong use of some class.</p>
<p>Basically, each constructor that may take only one arguement should be marked <code>explicit</code> unless the whole point is to allow implicit casting</p>
<h2>Avoid headers in headers</h2>
<p>Try to reduce as much as possible the number of includes in headers files.
This will generally help reduce the compilation time, specially for developper when just one header has been modified.
It may also avoid some error caused by conflicts between headers.
</p>
<p>If an object is only used by pointer or by reference in the class, it is not required to include his header, but just add a declaration before the class.<br/>
In this example, the class KFoo uses KBar per reference, so we don't need to include the KBar's header</p>
<pre>
#include <kfoobase.h>
<b class="keyword">class</b> KBar;
<b class="keyword">class</b> KFoo : <b class="keyword">public</b> KFooBase
{
<b class="keyword">public:</b>
<i class="comment">/* [...] */</i>
void myMethod( const & KBar );
};
</pre>
<h2>Documentation</h2>
<p>Every class and method should be well documented. Read the <a href="http://developer.kde.org/policies/documentationpolicy.php">KDE Library Documentation Policy</a></p>
<p>Also don't forget the license headers and copyrights in each files. As stated in the <a href="http://developer.kde.org/policies/licensepolicy.html">Licensing Policy</a>, kdelibs code must be in the LGPL, BSD, or X11 license. </p>
<p style="text-align:right">
<small> Author: <em> Olivier Goffart <a href="mailto:ogoffart@kde.org">ogoffart@kde.org</a></em><br/>
<em>2006-03-05</em></small></p>
</div>
</body>
</html>