Coding Standards
From KatWiki
| Table of contents |
Copyright notice
The following copyright notice should appear at the beginning of every file of the Kat project (.cpp, .h). If you find a file which does not contain this copyright notice or does contain a notice not conforming with this standard, please fix it and commit it to the CVS.
/* * This file is part of the Kat Desktop Search Environment project * Copyright (C) 2005-2006 Roberto Cappuccio <[email protected]> * * This program is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by the Free * Software Foundation; either version 2 of the License, or (at your option) * any later version. * * This program is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for * more details. * * You should have received a copy of the GNU General Public License along with * this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */
If you create a new piece of code or add substantial portions to an already existent piece of code, please add your name and email address immediately below the first 3 lines of the copyright notice.
/* * This file is part of the Kat Desktop Search Environment project * Copyright (C) 2005-2006 Roberto Cappuccio <[email protected]> * Other Developer <[email protected]> *
If you insert in Kat a piece of code extracted (or ported) from another project, please check first that the code is under GPL (or compatible) license and then insert the following lines into the copyright notice, below the first rows:
/* * This file is part of the Kat Desktop Search Environment project * Copyright (C) 2005-2006 Roberto Cappuccio <[email protected]> * * All the code (or portions of the code) contained in this file has * been taken (ported from language x) from the GPL project PROJECT NAME * PROJECT URL * Copyright (C) 2005 by NAME OF THE COPYRIGHT OWNER * NAME OF THE DEVELOPER : EMAIL@DEVELOPER *
Please notice the empty row after the last text row and before the rest of the copyright notice.
Variable names inside class definition
All private variables must begin with m_ like m_fooVar. The m_ stands for member.
private:
KatEngine* m_ke;
KatCatalog* m_cat;
NOT
private:
KatEngine* mKe;
KatCatalog* mCat;
NOT
private:
KatEngine* ke;
KatCatalog* cat;
Variable names (generic)
All variable names should begin with a lowercase letter. If the name is composed by more than one word, the words after the first should begin with an uppercase letter:
int metaData;
NOT
int metadata;
NOT
int Metadata;
NOT
int MetaData;
NOT
int _metaData;
Names of slot functions
All functions which are declared as slots must have a name beginning with "slot":
slotFileClicked()
NOT
fileClicked();
Tabs and indentations
Don't use tabs in the code. Use 4 spaces instead of a tab (all modern editors have an option for setting this behaviour). Use indentation only when really needed:
int a; QString b; char* c;
NOT
int a; QString b; char* c;
Spaces
Don't leave spaces at the end of a row. Dont' leave spaces at the beginning of empty rows.
Operators and spaces
Put a space before and after each operator:
a = b;
NOT
a=b;
Indices and spaces
Put a space before and after each index:
a = [ b ];
NOT
a = [b];
Includes
- Include files external to the project (those with <>) should be listed first.
- Include files internal to the project (those with "") should be listed subsequently.
- Include files should be grouped by library and possibly sorted in alphabetical order inside each group.
Using this standard makes it easier to avoid duplicate inclusions.
Pointers and references
char* p = "flop"; char& c = *p;
NOT
char *p = "flop"; char &c = *p;
Reason: In C++, definitions are mixed with executable code. Here, p is being initialized, not *p. This is near-universal practice among C++ programmers; it is normal for C hackers to switch spontaneously as they gain experience.
Function names and parentheses
No space before parentheses (except after a control-flow keyword) is near-universal practice for C++. It identifies the parentheses as the function-call operator or declarator, as opposed to an expression or other overloaded use of parentheses.
void mangle()
NOT
void mangle ()
Parameters of functions and parentheses
To improve readability, use
void mangle( int parameterA, QString parameterB ) void mangle( 8, QString( "Hello" ) )
NOT
void mangle(int parameterA, QString parameterB)
void mangle(8, QString("Hello"))
Return values of functions
To improve readability, use
void mangle( int parameterA, QString parameterB )
static QString mangle( int parameterA, QString parameterB )
NOT
void mangle( int parameterA, QString parameterB )
static QString mangle( int parameterA, QString parameterB )
Long list of parameters
If the list of parameters of a function is very long, put every parameter on a separate line, indenting it under the first parameter.
int myComplicatedFunction ( unsigned unsignedValue,
int intValue,
char* charPointerValue,
int* intPointerValue,
myClass* myClassPointerValue,
unsigned* unsignedPointerValue );
Casting and parentheses
To visually differentiate casts from similar constructs, use
long a = (long)b;
NOT
long a = ( long )b;
Blocks and parentheses
Use
class myClass
{
//
};
NOT
class myClass {
//
};
Use
while ( true )
{
a++;
}
NOT
while ( true ) {
a++;
}
Use
try
{
//
}
catch (...)
{
//
}
NOT
try {
//
} catch(...) {
//
}
Enumerators
enum
{
space = _ISspace,
print = _ISprint,
cntrl = _IScntrl
};
NOT
enum { space = _ISspace, print = _ISprint, cntrl = _IScntrl };
Class declarations
- NO indentation before protected, private, slot, protected slot etc
- Blank line after protected, private, slot, protected slot etc. blocks.
- No extra blank line under protected, private, slot, protected slot keywords.
- Blank line after constructor and destructor.
- Blank line after the block of member properties.
class Word : public QListViewItem
{
public:
Word( QListView* parent ) : QListViewItem( parent ) {};
~Word() {};
int occurrences;
int Word::compare( QListViewItem*, int, bool ) const;
void Word::paintCell( QPainter*, const QColorGroup&, int, int, int );
private:
int whatever;
};
Comments
- Comments have to be inserted in the code in the c++ form (with //)
- All comments have to be written in English
- All comments should be written completely in lowercase characters.
- Use the NOTE keyword for comments that have particular relevance
- Use the FIXME keyword for comments regarding possible issues with current implementation
- Use the TODO keyword for comments regarding missing parts of code
Simplified conditional blocks
Use simplified blocks when possible:
if ( a == b )
c = d;
NOT
if ( a == b )
{
c = d;
}
Do not use ultra-simplified conditional blocks:
a ? b : c; // Please don't use this construct
Debugging messages
Use the kdDebug() function to emit messages for debugging purposes
kdDebug() << "the message" << endl;
NOT
cout << "the message" << endl;
Include files
Technique for preventing multiple inclusion of an include file
#ifndef _FOO_H
#define _FOO_H
//File here
#endif // _FOO_H
True and false
Use true and false instead of TRUE and FALSE. These are the C++ keywords after all.
Null pointer
A null pointer is 0, not 0l, 0L or NULL. Once again, this is C++, not C.
Enforce data encapsulation
Never specify public or protected accessibility for members of a class. The use of public variables is discouraged for the following reasons:
- A public variable represents a violation of one of the basic principles of object-oriented programming, namely, encapsulation of data. For example, if there is a class of the type BankAccount, in which account_balance is a public variable, the value of this variable may be changed by any user of the class. However, if the variable has been declared private, its value may be changed only by the member functions of the class.
- An arbitrary function in a program can change public data which may lead to errors that are difficult to locate.
- If public data is avoided, its internal representation may be changed without users of the class having to modify their code. A principle of class design is to maintain the stability of the public interface of the class. The implementation of a class should not be a concern for its users.
Names of getters and setters functions
If you encapsulate the data, that is, you only use private members, you have to define getters and setters functions in order to get and set that private members.
for a private member:
private int numberOfLeaves;
define a getter:
public int numberOfLeaves();
and a setter:
public void setNumberOfLeaves( int );
