Commit 5a6aa4bb authored by Leena Miettinen's avatar Leena Miettinen

Doc: edits to language and style

Removed duplicate info.

Reviewed-by: hjk
parent 1c036c43
......@@ -27,286 +27,265 @@
/*!
\contentspage{index.html}{Qt Creator}
\page coding-style.html
\contentspage{index.html}{Qt Creator}
\page coding-style.html
\title Qt Creator Coding Rules
\title Qt Creator Coding Rules
THIS IS PRELIMINARY.
\note This document is work in progress.
\section1 Introduction
The coding rules aim to guide Qt Creator developers, to help them write
understandable and maintainable code, and to minimize confusion and surprises.
The aim of this section is to serve as a guide for the developers, to aid us
to build understandable and maintainable code, to create less confusion and
surprises when working on Qt Creator.
As usual, rules are not set in stone. If you have a good reason to break one,
do so. But first make sure that at least some other developers agree with you.
As usual: Rules are not set in stone. If there's a good reason to break one,
do it, preferably after making sure that there are others agreeing.
To contribute to the main Qt Creator source, you should comply to the
following rules:
\list
\o The most important rule is: KISS (keep it short and simple). Always
choose the simpler implementation option over the more complicated one.
This makes maintenance a lot easier.
\o Write good C++ code. That is, readable, well commented when necessary,
and object-oriented.
\o Take advantage of Qt. Do not re-invent the wheel. Think about which parts
of your code are generic enough that they might be incorporated into
Qt instead of Qt Creator.
\o Adapt the code to the existing structures in Qt Creator.
If you have improvement ideas, discuss them with other developers
before writing the code.
\o Follow the guidelines in \l{Code Constructs}, \l{Formatting}, and
\l{Patterns and Practices}.
\o Document interfaces. Right now we use qdoc, but changing to doxygen
is being considered.
\endlist
This document is incomplete.
In general, if you want to contribute to the main source, we expect at least
that you:
\section1 Submitting Code
\list 1
\o The most important rule first: KISS (keep it simple ...): always
use a simple implementation in favor of a more complicated one.
This eases maintenance a lot.
\o Write good C++ code: Readable, well commented when necessary,
and taking advantage of the OO model. Follow the \l{Formatting} guidelines.
There are also certain \l{Code Constructs} that we try to follow.
\o Adapt the code to the structures already existing in Qt Creator, or in
the case that you have better ideas, discuss them with other developers
before writing the code.
\o Follow the \l{Patterns and practices} that we use in Qt Creator.
\o Take advantage of Qt. Don't re-invent the wheel. Think about what parts
of your code are generic enough that they might be incorporated into
Qt proper.
\o Document interfaces. Right now we use qdoc, but changing to doxygen
is being considered.
\endlist
To submit code to Qt, you must understand the tools and mechanics as well as
the philosophy behind Qt development. For more information about how to set up
the development environment for working on a Qt library and how to submit code
and documentation for inclusion to Qt, see
\l{http://qt.gitorious.org/qt/pages/QtContributionGuidelines}{Qt Contribution Guidelines}.
\section1 Binary and Source Compatibility
\section1 Submitting Code
The following list describes how the releases are numbered and defines
\e {binary compatibility} and \e {source code compatibility} between
releases:
\list
\o Qt Creator 2.0.0 is a \e {major release}, Qt Creator 2.1.0 is a \e {minor
release}, and Qt Creator 2.1.3 is a \e {patch release}.
\o \e {Backward binary compatibility} means that code linked to an
earlier version of the library still works.
\o \e {Forward binary compatibility} means that code linked to a
newer version of the library works with an older library.
\o \e {Source code compatibility} means that code compiles without
modification.
\endlist
We do not currently guarantee API nor ABI
(\l{http://en.wikipedia.org/wiki/Application_binary_interface}{application binary interface})
compatibility between major releases.
However, we try to preserve compatibility between minor and patch releases,
as follows:
\list
\o Preserve backward binary compatibility and backward source code
compatibility in minor releases.
\o Preserve backward and forward binary compatibility and forward and
backward source code compatibility in patch releases:
\list
\o Do not add or remove any public API (e.g. global functions,x
public/protected/private methods).
\o Do not reimplement methods (not even inlines,
nor protected or private methods).
\o Check BinaryCompatibilityWorkarounds for ways to preserve binary
compatibility.
\endlist
\endlist
See http://qt.gitorious.org/qt/pages/QtContributionGuidelines
\note This is not yet mandatory.
For more information on binary compatibility, see
\l{http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++}{Binary Compatibility Issues With C++}.
\section1 Code Constructs
\section1 Code Constructs
We have several guidelines on code constructs, some of these exist to
make the code faster, others to make the code clearer. Yet others
exist to allow us to take advantage of the strong type checking in C++.
Follow the guidelines for code constructs to make the code faster and
clearer. In addition, the guidelines allow you to take advantage of the strong
type checking in C++.
\list 1
\o Declaration of variables should wait as long as possible. The rule
is: "Don't declare it until you need it." In C++ there are a lot of
user defined types, and these can very often be expensive to
initialize. This rule connects to the next rule too.
\list
\o Prefer preincrement to postincrement whenever possible.
Preincrement is potentially faster than postincrement. Just
think about the obvious implementations of pre/post-increment. This
rule applies to decrement too:
\o Make the scope of a variable as small as possible.
\code
++T;
--U;
\o Prefer preincrement to postincrement whenever possible.
Preincrement has potential of being faster than postincrement. Just
think about the obvious implementations of pre/post-increment. This
rule applies to decrement too.
-NOT-
\code
++T;
--U;
-NOT-
T++; // not used in Qt Creator
U--; // not used in Qt Creator
\endcode
T++;
U--;
\endcode
\o Try to minimize evaluation of the same code over and over. This is
aimed especially at loops.
\o Try to minimize evaluation of the same code over and over. This is
aimed especially at loops:
\code
\code
Container::iterator end = large.end();
for (Container::iterator it = large.begin(); it != end; ++it) {
...;
}
-NOT-
for (Container::iterator it = large.begin();
it != large.end(); ++it) {
...;
}
\endcode
Container::iterator end = large.end();
for (Container::iterator it = large.begin(); it != end; ++it) {
...;
}
-NOT-
\o Using Qt's foreach is ok in non-time critical code when using a QTL
container. It is a nice way to keep line noise down and to give the
loop variable a proper name:
for (Container::iterator it = large.begin();
it != large.end(); ++it) {
...;
}
\endcode
\code
foreach (QWidget *widget, container)
doSomething(widget);
-VS-
\o You can use the Qt \c foreach loop in non-time-critical code with a Qt
container. It is a nice way to keep line noise down and to give the
loop variable a proper name:
Container::iterator end = container.end();
for (Container::iterator it = container.begin(); it != end; ++it)
doSomething(*it);
\endcode
\code
foreach (QWidget *widget, container)
doSomething(widget);
If the loop variable can be made const, do so. This can prevent
unnecessary detaching of shared data in some cases. So:
-NOT-
\code
foreach (const QString &name, someListOfNames)
doSomething(name);
Container::iterator end = container.end();
for (Container::iterator it = container.begin(); it != end; ++it)
doSomething(*it);
\endcode
- NOT -
Make the loop variable const, if possible. This might prevent
unnecessary detaching of shared data:
foreach (QString name, someListOfNames)
doSomething(name);
\endcode
\code
foreach (const QString &name, someListOfNames)
doSomething(name);
- NOT -
\section1 Formatting
foreach (QString name, someListOfNames)
doSomething(name);
\endcode
\section2 Naming rules
\endlist
\list
\o Class names are capitalized, and function names lowercased.
\o Variables and functions start with a lower case letter.
\o Enums are named like Classes, values are in loweri case, containing
some part of the name of the enum type.
\endlist
\section1 Formatting
\section2 Capitalizing Identifiers
\section2 Declaration of variables
Use \l{http://en.wikipedia.org/wiki/CamelCase}{camel case} in identifiers.
\list
\o Each consecutive word in a variable's name starts with a capital letter.
Capitalize the first word in an identifier as follows:
\o Avoid short (e.g., a, rbarr, nughdeget) names whenever possible.
Single character variable names are only okay for counters and
temporaries, where the purpose of the variable is obvious.
\list
\o Class names begin with a capital letter.
\o Function names begin with a lower case letter.
\o Variable names begin with a lower case letter.
\o Enum names begin with a capital letter. Enum values use lower case and
contain some part of the name of the enum type.
\endlist
\section2 Whitespace
\list
\o Use four spaces for indentation, no tabs.
\o Use blank lines to group statements together where suited.
\o Always use only one blank line.
\endlist
\section3 Pointers and References
For pointers or references, always use a single space before an asterisk (*)
or an ampersand (&), but never after.
Avoid C-style casts when possible:
\code
char *blockOfMemory = (char *)malloc(data.size());
char *blockOfMemory = reinterpret_cast<char *>(malloc(data.size()));
-NOT-
char* blockOfMemory = (char* ) malloc(data.size());
\endcode
Of course, in this particulare case, using \c new might be an even better
option.
\section3 Operator Names and Parentheses
Do not use spaces between operator names and function names. The equation
marks (==) are a part of the function name, and therefore, spaces make the
declaration look like an expression:
\code
operator==(type)
-NOT-
operator == (type)
\endcode
\section3 Function Names and Parentheses
Do not use spaces between function names and parentheses:
\code
void mangle()
-NOT-
void mangle ()
\endcode
\section3 Keywords
Always use a single space after a keyword, and before a curly brace:
\code
if (foo) {
}
-NOT-
\o Declare each variable on a separate line.
\code
QString a = "Joe";
QString b = "Foo";
-NOT-
QString a = "Joe", b = "Foo"; // not used in Qt Creator
\endcode
[Note that 'QString a = "Joe"' is formally calling a copy constructor
on a temporary constructed from a string literal and therefore has the
potential of being more expensive then direct construction by
'QString a("Joe")'. However the compiler is allowed to elide the copy
(even if it had side effects), and modern compilers typically do so.
Given these equal costs, Qt Creator code favours the '=' idiom as
it is in
line with the traditional C-style initialization, _and_ cannot be
mistaken as function declaration, _and_ reduces the level of nested
parantheses in more initializations.]
\o Avoid abbreviations
// Wrong
int a, b;
char *c, *d;
// Correct
int height;
int width;
char *nameOfThis;
char *nameOfThat;
\o Wait with declaring a variable until it is needed. This is especially
important when initialization is done at the same time.
\endlist
\section2 Pointers and references
\code
char *p = "flop";
char &c = *p;
-NOT-
char* p = "flop"; // not used in Qt Creator
char & c = *p; // not used in Qt Creator
\endcode
Also note that we will have:
\code
const char *p;
-NOT-
char const * p; // not used in Qt Creator
\endcode
Using a plain 0 for Null pointer constants is always correct and
least effort to type. So:
\code
void *p = 0;
-NOT-
void *p = NULL; // not used in Qt Creator
-NOT-
void *p = '\0'; // not used in Qt Creator
-NOT-
void *p = 42 - 7 * 6; // also not used in Qt Creator
\endcode
Note: As an exception, imported third party code as well as code
interfacing the "native" APIs (src/support/os_*) can use NULL.
\section2 Operator names and parentheses
\code
operator==(type)
-NOT-
operator == (type) // not used in Qt Creator
\endcode
The == is part of the function name, separating it makes the
declaration look like an expression.
\section2 Function names and parentheses
\code
void mangle()
-NOT-
void mangle () // not used in Qt Creator
\endcode
\section2 Indentation
Four spaces, no tabs.
\section2 Whitespace
\list
\o Use blank lines to group statements together where suited.
\o Always use only one blank line.
\o Always use a single space after a keyword, and before a curly brace.
\endlist
\code
// Wrong
if(foo){
}
\endcode
// Correct
if (foo) {
\section2 Braces
As a base rule, place the left curly brace on the same line as the
start of the statement:
\code
if (codec) {
}
\endcode
For pointers or references, always use a single space before '*' or '&',
but never after.
Avoid C-style casts when possible.
\code
// Wrong
char* blockOfMemory = (char* ) malloc(data.size());
-NOT-
// Correct
char *blockOfMemory = (char *)malloc(data.size());
char *blockOfMemory = reinterpret_cast<char *>(malloc(data.size()));
\endcode
Of course, in this particulare case, using \c new might be an even better
option.
Braces
As a base rule, the left curly brace goes on the same line as the
start of the statement:
\code
// Wrong
if (codec)
{
}
\endcode
// Correct
if (codec) {
}
\endcode
Exception: Function implementations and class declarations always have
the left brace in the beginning of a line:
Exception: Function implementations and class declarations always have
the left brace on the start of a line:
\code
\code
static void foo(int g)
{
qDebug("foo: %i", g);
......@@ -315,12 +294,21 @@ Braces
class Moo
{
};
\endcode
\endcode
Use curly braces when the body of a conditional statement contains more
than one line, and also if a single line statement is somewhat complex.
Otherwise, omit them:
\code
if (address.isEmpty())
return false;
for (int i = 0; i < 10; ++i)
qDebug("%i", i);
-NOT-
Use curly braces when the body of a conditional statement contains more
than one line, and also if a single line statement is somewhat complex.
\code
// Wrong
if (address.isEmpty()) {
return false;
}
......@@ -328,29 +316,21 @@ Braces
for (int i = 0; i < 10; ++i) {
qDebug("%i", i);
}
\endcode
// Correct
if (address.isEmpty())
return false;
Exception 1: Use braces also if the parent statement covers several
lines or if it wraps:
for (int i = 0; i < 10; ++i)
qDebug("%i", i);
\endcode
Exception 1: Use braces also if the parent statement covers several
lines / wraps
\code
// Correct
\code
if (address.isEmpty()
|| !isValid()
|| !codec)
return false;
\endcode
\endcode
Note: This could be re-written as:
\note This could be re-written as:
\code
// Als correct
\code
if (address.isEmpty())
return false;
......@@ -359,512 +339,524 @@ Braces
if (!codec)
return false;
\endcode
\endcode
Exception 2: Use braces also in if-then-else blocks where either the
if-code or the else-code covers several lines
\code
// Wrong
if (address.isEmpty())
Exception 2: Use braces also in if-then-else blocks where either the
if-code or the else-code covers several lines:
\code
if (address.isEmpty()) {
--it;
else {
} else {
qDebug("%s", qPrintable(address));
++it;
}
// Correct
if (address.isEmpty()) {
-NOT-
if (address.isEmpty())
--it;
} else {
else {
qDebug("%s", qPrintable(address));
++it;
}
\endcode
// Wrong
if (a)
\code
if (a) {
if (b)
...
else
...
}
// Correct
if (a) {
-NOT-
if (a)
if (b)
...
else
...
}
\endcode
\endcode
Use curly braces when the body of a conditional statement is empty
\code
// Wrong
while (a);
Use curly braces when the body of a conditional statement is empty:
// Correct
\code
while (a) {}
\endcode
-NOT-
\section2 Parentheses
Use parentheses to group expressions:
\code
// Wrong
if (a && b || c)
while (a);
\endcode
\section2 Parentheses
Use parentheses to group expressions:
// Correct
\code
if ((a && b) || c)
// Wrong
a + b & c
-NOT-
if (a && b || c)
\endcode
// Correct
\code
(a + b) & c
\endcode
\section2 Line breaks
Keep lines shorter than 100 characters; insert line breaks if necessary.
Commas go at the end of a broken line; operators start at the beginning
of the new line. The operator is at the end of the line to avoid having
to scroll if your editor is too narrow.
\code
// Wrong
if (longExpression +
otherLongExpression +
otherOtherLongExpression) {
}
// Correct
if (longExpression
+ otherLongExpression
+ otherOtherLongExpression) {
}
\endcode
-NOT-
a + b & c