(→Parenthesis) |
|||
| Line 406: | Line 406: | ||
=== if, for, while and similar macros rules === | === if, for, while and similar macros rules === | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
=== Use block braces === | === Use block braces === | ||
| Line 444: | Line 437: | ||
} | } | ||
}} | }} | ||
| + | === Parenthesis === | ||
| + | We prefer function definition and function call with no space after the opening brace and before the closing brace. | ||
| + | |||
| + | *coding-style-check-Parenthesis.sh | ||
| + | *astyle | ||
| + | |||
| + | Download the scripts: [[Media:Parenthesis.tar.gz]] | ||
== Use all the scripts == | == Use all the scripts == | ||
This document describes the recommended coding style for kdepim and akonadi. Nobody is forced to use this style, but to have consistent formatting of the source code files it is strongly recommended to make use of it.
In short: Kdepim and akonadi coding style follows the Kdelibs coding style.
We need at least:
astyle is a pretty tool to make such changes. But astyle doesn't implement (yet) all the specification rules. You can find below some awk-scripts which help us to make most of the changes. The last part must be done manually.
As discussed at the KDEPIM meeting, Berlin, 3 March 2013, all the files of KDEPIM will be reviewed to follow the coding style. This will be done over a long time, directory after directory, for each of the rules defined above. For each rule, one can find one or two script(s).
The main part of the changes can be done with astyle: http://astyle.sourceforge.net/
The first script is to check a single file or a complete directory for all .h and .cpp files.
If present, the second script makes the changes for a single file or a complete directory for all .h and .cpp files. For some complicated situations, the script makes no change.
One can use the scripts for own work.It is recommanded to use them in this order.
If a .no_coding_style file is present on a directory, the test will not be done.
If a .no_recursion file is present on a directory, we do not explore the subdirectory(ies)
astyle --indent=spaces
Download the scripts: Media:Tabs.tar.gz
The output of the check script is:
check the file ktnefparser.cpp 308: Tab at 16: stream_ >> i; // i <- attribute type & name 311: Tab at 16: stream_ >> i; // i <- data length 326: Tab at 22: case attATTACHMENT: // try to get attachment info 367: Tab at 16: stream_ >> u; // u <- checksum
This shows:
astyle --indent=spaces
Download the scripts: Media:Trim.tar.gz
The output of the check script is:
check the file trim.cpp 51: Space(s) at end of line (28): QVariant m_matchData;
This shows:
Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Whitespace
Download the scripts: Media:Twice.tar.gz
The output of the check script is:
check the file enclosure.cpp 25: next empty line found 26: next empty line found 30: next empty line found
This shows:
The change script:
Some of the sources have a first empty lines, some have one or more empty last line(s).
Download the scripts: Media:First.tar.gz
The output of the check script is:
check the file trim.cpp The first line is empty The last line is empty
The change script:
Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Whitespace
For most of the keywords, it is not necessary to make a test. Because the sources have been already compiled. For example this code never appear in a source:
inta; floatb;
Some of the keywords are alone in the statement, such as break and continue. No test is necessary.
The only tests we have to do are the ones where a keyword is (or can be) followed by a sign ( { [ :
These are: alignas decltype alignof noexcept typeid asm static_assert switch if catch while for sizeof new Q_FOREACH do try enum union Q_FOREVER bool char char16_t char32_t double float int long wchar_t signed unsigned short
For only one keyword:
For all keywords above:
Download the scripts: Media:SpaceAfter.tar.gz
The output of the check script is:
KDE TechBase check the file contactstreemodel.cpp
98: if( at 10: if(contact.realName().isEmpty()) {
99: if( at 12: if(contact.preferredEmail().isEmpty()) {
The change script:
Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Braces
The following code:
if (a > b) c = 123;
is correct, but we prefer the block:
if (a > b) {
c = 123;
}
which is easier to debug, read and to modify.
It is also possible to put a breakpoint at the line in the block.
As the awk-script is too simple to recognize all the if-statements, we get some false alarm and we can't make the changes automatically.
Download the scripts: Media:One-Line-If.tar.gz
The output of the check script is:
check the file if-example.cpp 25: one-line-if found
Looking over the git-history, one can find some "pedantic" changes. These are changes to make a better code. The most of them are at the use of macro, where it is not necessary to have a ; at the end ofthe command. The script make a check over all these: AKTEST_MAIN;MAKE_CMD_ROW;Q_DECLARE_FLAGS;Q_PRIVATE_SLOT;Q_DECLARE_METATYPE;Q_DECLARE_OPERATORS_FOR_FLAGS;Q_DE CLARE_PRIVATE;Q_DECLARE_PUBLIC;Q_DISABLE_COPY;K_GLOBAL_STATIC;Q_IMPORT_PLUGIN;Q_PROPERTY;Q_UNUSED;QTEST_KDEMAIN;QTEST_MAIN
Download the scripts: Media:Pedantic.tar.gz
We prefer having a space before the keyword public at the definition of a new class:
class DbException : public Akonadi::Exception
{
...
};
Download the scripts: Media:Public.tar.gz
Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Qt_Includes
We prefer no space at the beginning of the directive. Some (not many) files need to be corrected to unify to all the other files.
// some files use this # include <A/b> // we prefer, to unify the coding style #include <A/b>
Download the scripts: Media:Space-Include.tar.gz
Instead of having an untyped enum such as:
enum {
aElement= 123
}
we prefer a #define directive:
#define aElement 123
Download the scripts: Media:Enum.tar.gz
The most compilers do not complain such a code:
enum mytype {
aElement,
bElement,
}
The last element is empty. We prefer a "pedantic" code such as:
enum mytype {
aElement,
bElement
}
The output of the check script is:
check the file enum-example.cpp enum with ,} found at 3-> bElement, 4-> }
Download the scripts: Media:Enum-Pedantic.tar.gz
The declaration S *D; declares D as a pointer to the type determined by decl-specifier-seq S.
The most compilers do not make any difference for such lines of code:
int *a; int* b; int * c
We prefer the first one, without a space beetwen the star and the name of the variable:
int *a;
The same rule may be use for:
myFunction(int &a, int& b, int & c)
{
// some lines
}
We prefer:
myFunction(int &a, int &b, int &c)
The awk-script checks also the occurences of:
Not all the ouputs are real errors. Some codings might be correct.
astyle --reference=name --align-pointer=name
Note that astyle makes also changes within the macros SIGNAL and SLOT, which aren't desired. This can be corrected with a Qt-utility: normalize filename
Some lines with "type & name..." must be manually corrected.
Download the scripts: Media:NO-Space.tar.gz
The script gives informations about the found line(s).
This example shows the indentation we prefer:
class myClass {
// some lines
public:
myClass(int r, int b, int i, int j)
: r(0)
, b(i)
, i(5)
, j(13)
{
// more lines
}
Download the scripts: Media:Default.tar.gz
This example shows the indentation we prefer:
switch (a) {
case one:
// some lines
break;
case two:
// some lines
break;
default:
// some lines
break;
}
Download the scripts: Media:Switch.tar.gz
Even for block with only one statement, we prefer to use braces such as:
if (condition) {
statement;
}
This should be used with the keywords if, for, while and FOREACH.
The output of the check script is:
check the file test-if.cpp
62: if without { at end of line: if ( collection.cachePolicyLocalParts() )
Download the scripts: Media:If.tar.gz
But we get some false alarm with statement over more than one line:
if (condition_1
&& condition_2) {
statement;
}
We prefer function definition and function call with no space after the opening brace and before the closing brace.
Download the scripts: Media:Parenthesis.tar.gz
All the scripts can be used with one only script.
Download the scripts: Media:All.tar.gz
The comments might contain some keyword. It is very difficult to avoid the confusion with the very simple awk-scripts. We prefer to change all the comments with the same number of empty lines.
Download the scripts: Media:Comments.tar.gz
It is very difficult to parse the strings correctly, so we prefer to change them to an empty string.
Download the scripts: Media:Strings.tar.gz
As a first approach, not any object may have binary change after applying one of the rules. To check this, one uses the Md5sum-the-Objects.sh. Download the script: Media:Md5sum-the-Objects.sh.gz Same for the libs. Use the Md5sum-the-Libs.sh. Download the script: Media:Md5sum-the-Libs.sh.gz
The script can be used with one of the commands:
An example:
cd <some_kdepim_directory> mkdir build cd build ccmake ../ make
Scanning dependencies of target gpgmepp [ 0%] Building CXX object gpgme++/CMakeFiles/gpgmepp.dir/gpgmepp_automoc.cpp.o [ 0%] Building CXX object gpgme++/CMakeFiles/gpgmepp.dir/exception.cpp.o [ 0%] Building CXX object gpgme++/CMakeFiles/gpgmepp.dir/context.cpp.o ...
Check-the-Objects.sh save
The script makes a copy of all the objects and a "time stamp":
save the object ./kholidays/tests/CMakeFiles/testzodiac.dir/testzodiac.cpp.o save the object ./kholidays/tests/CMakeFiles/testzodiac.dir/testzodiac_automoc.cpp.o ... all objects are saved
Now, one makes somes change(s) on the source(s) and:
make
Depending on the Makefile, some objects will be compiled again:
Scanning dependencies of target akonadi-kde [ 17%] Building CXX object akonadi/CMakeFiles/akonadi-kde.dir/entitytreeview.cpp.o [ 17%] Building CXX object akonadi/CMakeFiles/akonadi-kde.dir/itemfetchjob.cpp.o [ 17%] Building CXX object akonadi/CMakeFiles/akonadi-kde.dir/statisticsproxymodel.cpp.o ... Scanning dependencies of target akonadi-kmime [ 56%] Building CXX object akonadi/kmime/CMakeFiles/akonadi-kmime.dir/standardmailactionmanager.cpp.o
Check-the-Objects.sh test
The script finds all the new objects, makes a comparision with the saved version:
test the object ./akonadi/CMakeFiles/akonadi-kde.dir/statisticsproxymodel.cpp.o test the object ./akonadi/CMakeFiles/akonadi-kde.dir/entitytreeview.cpp.o test the object ./akonadi/CMakeFiles/akonadi-kde.dir/itemfetchjob.cpp.o test the object ./akonadi/kmime/CMakeFiles/akonadi-kmime.dir/standardmailactionmanager.cpp.o all tests are OK
If we add or remove some lines, the debug informations included in the object file will be change also.
This is the case with the test/change of "Only single empty lines should be used", "First line, last line(s) may not be empty" and some more test/change below (adding some blocks with { and }).
For this reason it is no more possible to compare the objects. We have to compare the assembler files. This works pretty well for the version with CMAKE_BUILD_TYPE set to release. For the version with CMAKE_BUILD_TYPE set to debug, we must remove all the debug informations before the comparision could take place.
To generate the assembler files, we only need to modify the build.make in every folder.
The script Prepare-build_make_files.sh works on the all directory, finds the line with the compiler command, duplicates the line, add a -S option and changes the name of the output to somename.s. After a new make command, we can save all the assembler files with the script Check-the-assembler_code.sh. Download the script: Media:Prepare-build_make_files.gz
The debug informations change with the changes of line numbers. We drop all these debug informations before making the test.
The script to check the assembler files can be used in the same way as the one above (Check-the-Objects.sh). To check this, one uses the Check-the-assembler_code.sh. Download the script: Media:Check-the-assembler_code.sh.gz
The script can be used with one of the commands:
