It is very difficult to parse the strings correctly, so we prefer to change them to an empty string.

+

It is also possible to put a breakpoint at the line in the block.

−

*Strings.awk

+

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:Strings.tar.gz]]

+

*coding-style-check-OneLine-If.sh

+

*coding-style-check-OneLine-Else.sh

+

+

+

The output of the '''check''' script is:

+

{{Output|1=check the file if-example.cpp

+

25: one-line-if found

+

}}

+

+

=== No space between some keywords ===

+

+

We don't want to have a space:

+

*between '''&''' and '''>'''

+

*between '''*''' and '''>'''

+

*between '''(''' and ''')''', an empty parameter list.

+

+

*coding-style-check-No-Space.sh

+

+

The output of the '''check''' script is:

+

{{Output|1=check the file NO-space-example.cpp

+

15: Star<Space> found. Check it. int * myA;

+

28: AND<Space> found. Check it. abc( & myA);

+

}}

+

+

=== No space around the index of an array ===

+

+

We don't want to have spaces around the index of an array element.

+

+

*coding-style-check-No-Space.sh

+

+

The output of the '''check''' script is:

+

{{Output|1=check the file NO-space-example.cpp

+

15: [<Space> found. Check it. a = b[ i ];

+

15: <Space>] found. Check it. a = b[ i ];

+

}}

+

+

=== No space around an expression surrounded with braces ===

+

+

We prefer function definition and function call with no space after the opening brace and before the closing brace.

+

+

*coding-style-check-Parenthesis.sh

+

*This is well done with astyle:

+

{{Output| 1=astyle --unpad-paren

+

}}

+

Note that astyle makes also changes within the macros SIGNAL and SLOT, which aren't desired.

+

This can be corrected with a Qt-utility qt5/qtrepotools/util/normalize/normalize:

+

{{Output| 1=normalize --modify ''filename''

+

}}

+

+

=== No space before ''':''' in a case statement ===

+

+

We don't provide (yet) any check for this rule.

+

+

=== No space before ''';''' at the end of statement ===

+

+

We don't provide (yet) any check for this rule.

+

+

=== No ''');''' alone in a line ===

+

+

This is sometime to be find with a function call with many arguments, listed on many lines.

+

*coding-style-check-Parenthesis-alone.sh

+

+

== Use all the scripts ==

+

+

All the scripts can be used with one only script.

== Check the objects and the libs ==

== Check the objects and the libs ==

−

As a first approach, not any object may have binary change after applying one of the rules.

+

Since the changes described above are only coding style changes, they are ignored by the compiler.

−

To check this, one uses the '''Md5sum-the-Objects.sh'''. Download the script: [[Media:Md5sum-the-Objects.sh.gz]]

+

Therefore, the result of the compilation is expected to be exactly the same after applying any of the rules.

−

Same for the libs. Use the '''Md5sum-the-Libs.sh'''. Download the script: [[Media:Md5sum-the-Libs.sh.gz]]

+

+

To check this, one uses the '''Md5sum-the-Objects.sh'''.

+

Same for the libs. Use the '''Md5sum-the-Libs.sh'''.

The script can be used with one of the commands:

The script can be used with one of the commands:

Line 537:

Line 637:

== Check the assembler files ==

== Check the assembler files ==

−

If we add or remove some lines, the debug informations included in the object file will be change also.

+

If we add or remove some lines, the debug information included in the object file will 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 }).

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 }).

Line 544:

Line 644:

We have to compare the assembler files.

We have to compare the assembler files.

This works pretty well for the version with '''CMAKE_BUILD_TYPE''' set to ''release''.

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.

+

For the version with '''CMAKE_BUILD_TYPE''' set to ''debug'', we must remove all the debug information before the comparision can take place.

=== Generate the assembler files ===

=== Generate the assembler files ===

Line 553:

Line 653:

duplicates the line, add a ''-S option'' and changes the name of the output to ''somename.s''.

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'''.

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]]

−

=== Remove the debug informations ===

+

=== Remove the debug information ===

−

The debug informations change with the changes of line numbers.

+

The debug information changes with the changes of line numbers.

−

We drop all these debug informations before making the test.

+

We drop all the debug information 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).

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]]

+

To check this, one uses the '''Check-the-assembler_code.sh'''.

The script can be used with one of the commands:

The script can be used with one of the commands:

Line 567:

Line 666:

* test

* test

* clean

* clean

+

+

== The results of the migration ==

+

+

The results can be seen [http://techbase.kde.org/ResultsOfTheMigration here].

Purpose of this document

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.

Why is coding Style useful?

Let us make a comparision with real life.
To make an addition, one can write:

123
+ 456
==========
= 579

But we have learned in primary school to write:

Addition
123
+456
====
=579

Which is much more readable, easy to control (or debug).

This is Coding Style: not mandatory but very useful and pretty to read.

What do we need?

We need at least:

a specification (a set of rules) for the coding style of the sources

some tools to check the sources against the specification

some tools to change the sources

astyle is a suitable 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 check all the rules.

You can find below some awk-scripts which help us to make most of the changes.
The last part must be done manually.

The specification rules of coding style for kdepim and akonadi

Indentation with four spaces, don't use any <TAB>s

Trim the lines

Only single empty lines

The first line and the last line(s) may not be empty

Only one statement per line

Variable declaration

Only one declaration per line

Use a space after each keyword, but not after a cast

Use a space after the name of the class

include directive

Place * and & next to the variable

Use namespace foo { in the same line

Each member initialization of a method in a separate line

Surround all operators with spaces

switch rules

try-catch rules

if, for, while and similar macros rules

typedef struct statement over more lines

Don't use &, without a variable

Don't use untyped enum

Don't use enum with empty member

No ; after some macros

No "one line" ifforwhile statement

No code after {

No code before } (but else)

No header and body code in the same line, even empty body

No space between some keywords

No space around the index of an array

No space around an expression surrounded with braces

No space before : in a case statement

No space before ; at the end of statement

No ); alone in a line

Migration

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, there are one or two script(s).

Download Coding Style

Two scripts to check all the rules and to make the all the changes

Most of the rules can be checked with the scripts below.
For some of the rules, we don't have a script to change the sources.
It is better first to make a check for such a rule, second to make the modification(s) manually to suscript the rule(s).

There are two scripts that run all the checks and apply all the changes at once:

All-Check.sh

Change-All.sh

For each specification rule, the name of the scripts to check and apply the changes
are given at the beginning of the section.

The scripts to check and to make the changes

The first script is to check a single file or all .h and .cpp files in a directory.

If present, the second script applies the changes.
For some complicated situations, the script makes no change.

You can use the scripts for your own work. It is recommended to use them in this order.

Don't test all directories

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)

try-catch rules

if, for, while (and similar macros) rules

Even for blocks 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 similar macros.
The output of the check script is:

check the file test-if.cpp
62: if without { at end of line: if ( collection.cachePolicyLocalParts() )

coding-style-check-If.sh

coding-style-check-Else.sh

coding-style-check-For.sh

coding-style-check-While.sh

astyle

But we get some false alarm with statements that extend over more than one line:

if (condition_1
&& condition_2) {
statement;
}

typedef struct statement over more lines

This example shows the indentation we prefer:

typedef struct foo {
// some lines
}

coding-style-check-TypedefStruct.sh

Don't use & without a variable

Don't use untyped enum

Instead of having an untyped enum such as:

enum {
aElement= 123
}

we prefer a #define directive:

#define aElement 123

Don't use enum with empty member

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
}

coding-style-check-Enum-Pedantic.sh

The output of the check script is:

check the file enum-example.cpp
enum with ,} found at
3-> bElement,
4-> }

No ; after some macros

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;QTEST_KDEMAIN;QTEST_MAIN

No space around an expression surrounded with braces

We prefer function definition and function call with no space after the opening brace and before the closing brace.

coding-style-check-Parenthesis.sh

This is well done with astyle:

astyle --unpad-paren

Note that astyle makes also changes within the macros SIGNAL and SLOT, which aren't desired.
This can be corrected with a Qt-utility qt5/qtrepotools/util/normalize/normalize:

normalize --modify filename

No space before : in a case statement

We don't provide (yet) any check for this rule.

No space before ; at the end of statement

We don't provide (yet) any check for this rule.

No ); alone in a line

This is sometime to be find with a function call with many arguments, listed on many lines.

coding-style-check-Parenthesis-alone.sh

Use all the scripts

All the scripts can be used with one only script.

Check the objects and the libs

Since the changes described above are only coding style changes, they are ignored by the compiler.
Therefore, the result of the compilation is expected to be exactly the same after applying any of the rules.

To check this, one uses the Md5sum-the-Objects.sh.
Same for the libs. Use the Md5sum-the-Libs.sh.

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

Check the assembler files

If we add or remove some lines, the debug information included in the object file will 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 information before the comparision can take place.

Generate the assembler files

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.

Remove the debug information

The debug information changes with the changes of line numbers.
We drop all the debug information 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.