Difference between revisions of "Policies/Kdepim Coding Style"

Jump to: navigation, search
(The rules for Kdepim)
(No twice empty lines)
(93 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
== Purpose of this document ==
 
== Purpose of this document ==
  
This document describes the recommended coding style for kdepim. Nobody is
+
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
 
forced to use this style, but to have consistent formatting of the source code
 
files it is strongly recommended to make use of it.
 
files it is strongly recommended to make use of it.
  
'''In short: Kdepim coding style follows the'''
+
''In short: Kdepim and akonadi coding style follows the''
 
[http://techbase.kde.org/Policies/Kdelibs_Coding_Style Kdelibs coding style].
 
[http://techbase.kde.org/Policies/Kdelibs_Coding_Style Kdelibs coding style].
  
== The rules for Kdepim ==
+
== The rules for kdepim and akonadi ==
  
 
*don't use any <TAB>s
 
*don't use any <TAB>s
 
*Trim the lines
 
*Trim the lines
 
*Only single empty lines should be used
 
*Only single empty lines should be used
 +
*The first line, the last line(s) may not be empty
 +
*Use one space after each keyword, but not after a cast
 +
*no "one line" if-statement
  
 
== Migration ==
 
== Migration ==
Line 23: Line 26:
 
rules defined above.  For each rule, one can find one or two script(s).   
 
rules defined above.  For each rule, one can find one or two script(s).   
  
The first script is to check a single file or a complete directory for all .h and
+
== Check the objects ==
 +
 
 +
As a first approach, not any object may have binary change after applying one of the rules.
 +
To check this, one uses the '''Check-the-Objects.sh'''. Download the script: [[Media:Check-the-Objects.sh.gz]]
 +
 
 +
The script can be used with one of the commands:
 +
* save
 +
* test
 +
* clean
 +
 
 +
'''An example:'''
 +
 
 +
{{Input|1=cd <some_kdepim_directory>
 +
mkdir build
 +
cd build
 +
ccmake ../
 +
make}}
 +
{{Output|1=<span style="color:Fuchsia">Scanning dependencies of target gpgmepp</span>
 +
[  0%] <span style="color:green">Building CXX object gpgme++/CMakeFiles/gpgmepp.dir/gpgmepp_automoc.cpp.o</span>
 +
[  0%] <span style="color:green">Building CXX object gpgme++/CMakeFiles/gpgmepp.dir/exception.cpp.o</span>
 +
[  0%] <span style="color:green">Building CXX object gpgme++/CMakeFiles/gpgmepp.dir/context.cpp.o</span>
 +
...}}
 +
 
 +
{{Input|1=Check-the-Objects.sh save}}
 +
The script makes a copy of all the objects and a "time stamp":
 +
{{Output|1=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:
 +
 
 +
{{Input| 1=make}}
 +
 
 +
Depending on the Makefile, some objects will be compiled again:
 +
 
 +
{{Output| 1=<span style="color:Fuchsia">Scanning dependencies of target akonadi-kde</span>
 +
[ 17%] <span style="color:green">Building CXX object akonadi/CMakeFiles/akonadi-kde.dir/entitytreeview.cpp.o</span>
 +
[ 17%] <span style="color:green">Building CXX object akonadi/CMakeFiles/akonadi-kde.dir/itemfetchjob.cpp.o</span>
 +
[ 17%] <span style="color:green">Building CXX object akonadi/CMakeFiles/akonadi-kde.dir/statisticsproxymodel.cpp.o</span>
 +
...
 +
<span style="color:Fuchsia">Scanning dependencies of target akonadi-kmime</span>
 +
[ 56%] <span style="color:green">Building CXX object akonadi/kmime/CMakeFiles/akonadi-kmime.dir/standardmailactionmanager.cpp.o</span>}}
 +
 
 +
{{Input|1=Check-the-Objects.sh test}}
 +
 
 +
The script finds all the new objects, makes a comparision with the saved version:
 +
{{Output|1=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 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.
 +
 
 +
=== 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'''.
 +
Download the script: [[Media:Prepare-build_make_files.sh.gz]]
 +
 
 +
=== Remove the debug informations ===
 +
 
 +
The biggest part of the debug informations beginns with the directive line
 +
*.Ldebug_info0
 +
We drop all the next lines.
 +
 
 +
We drop also the lines with the directive .loc
 +
They contain an information about the source line (here 123) we need later to drop the lines
 +
* movl $123, %edx
 +
* movl $123, %ecx
 +
 
 +
The lines with
 +
* .string "/home/guy-kde/projects/kdepimlibs/akonadi/agentbase.cpp:454"
 +
will be also removed.
 +
 
 +
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:
 +
* save
 +
* test
 +
* clean
 +
 
 +
== The scripts ==
 +
The first script is '''to check''' a single file or a complete directory for all .h and
 
.cpp files.
 
.cpp files.
  
If present, the second script makes the changes for a single file or a complete
+
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
 
directory for all .h and .cpp files.  For some complicated situations, the
 
script makes no change.
 
script makes no change.
  
 
One can use the scripts for own work.It is recommanded to use them in this order.
 
One can use the scripts for own work.It is recommanded to use them in this order.
=== The scripts ===
 
  
 
==== don't use any <TAB>s ====
 
==== don't use any <TAB>s ====
 
*coding-style-check-Tabs.sh
 
*coding-style-check-Tabs.sh
 
*coding-style-change-Tabs.sh
 
*coding-style-change-Tabs.sh
 +
 +
Download the scripts: [[Media:Tabs.tar.gz]]
  
 
The output of the '''check''' script is:
 
The output of the '''check''' script is:
Line 58: Line 159:
 
*coding-style-check-Trim.sh
 
*coding-style-check-Trim.sh
 
*coding-style-change-Trim.sh
 
*coding-style-change-Trim.sh
 +
 +
Download the scripts: [[Media:Trim.tar.gz]]
 +
 
The output of the '''check''' script is:
 
The output of the '''check''' script is:
 
  {{Output|1=check the file /home/guy-kde/Software/coding-style-check/trim.cpp
 
  {{Output|1=check the file /home/guy-kde/Software/coding-style-check/trim.cpp
Line 70: Line 174:
 
*remove all trailing space(s).
 
*remove all trailing space(s).
  
==== Check for multiple empty lines ====
+
==== Only single empty lines should be used ====
 +
Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Whitespace
  
 
*coding-style-check-Twice.sh
 
*coding-style-check-Twice.sh
Line 76: Line 181:
  
 
The output of the '''check''' script is:
 
The output of the '''check''' script is:
{{Output|1=check the file /home/guy-kde/projects/kdepimlibs/syndication/rss2/enclosure.cpp
+
{{Output|1=check the file /home/guy-kde/projects/kdepimlibs/syndication/rss2/enclosure.cpp
    1->25: next empty line found
+
1->25: next empty line found
    2->26: next empty line found
+
2->26: next empty line found
    3->30: next empty line found}}
+
3->30: next empty line found}}
 
      
 
      
 
This shows:
 
This shows:
Line 87: Line 192:
 
The '''change''' script:
 
The '''change''' script:
 
*removes all the next empty line(s).
 
*removes all the next empty line(s).
 +
 +
==== First line, last line(s) may not be empty ====
 +
 +
Some of the sources have a first empty lines, some have one or more empty last line(s).
 +
*coding-style-check-First-Last.sh
 +
*coding-style-change-First-Last.sh
 +
 +
The output of the '''check''' script is:
 +
{{Output|1=check the file /home/guy-kde/Software/coding-style-check/trim.cpp
 +
The first line is empty
 +
The last line is empty}}
 +
   
 +
The '''change''' script:
 +
*removes the first line if empty, all the last empty line(s).
 +
 +
==== Use one space after each keyword, but not after a cast ====
 +
 +
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:
 +
{{Output|1=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:
 +
*coding-style-check-SpaceAfterKeyword.sh
 +
*coding-style-change-SpaceAfterKeyword.sh
 +
 +
For '''all''' keywords above:
 +
*coding-style-check-SpaceAfter.sh
 +
*coding-style-change-SpaceAfter.sh
 +
 +
The output of the '''check''' script is:
 +
{{Output|1=check the file /home/guy-kde/projects/kdepimlibs/akonadi/contact/contactstreemodel.cpp
 +
1->98:  if( at 10:          if( contact.realName().isEmpty() ) {
 +
2->99:  if( at 12:            if( contact.preferredEmail().isEmpty() ) {
 +
}}
 +
 +
The '''change''' script:
 +
*puts a space after the keyword.
 +
 +
====no "one line" if-statement====
 +
 +
Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Braces
 +
 +
The following code:
 +
{{Output|1=if ( a > b ) c = 123;}}
 +
is correct, but we prefer the block:
 +
{{Output|1=if ( a > b ) {
 +
  c = 123;
 +
} }}
 +
which is easier to read, 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.
 +
 +
*coding-style-check-One-Line-If.sh
 +
 +
The output of the '''check''' script is:
 +
{{Output|1=check the file /home/guy-kde/Software/coding-style-check/if-example.cpp
 +
1->25: one-line-if found}}
 +
 +
====Pedantic====
 +
 +
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'''
 +
 +
*coding-style-check-Pedantic.sh
 +
 +
====#include directive====
 +
 +
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.
 +
 +
{{Output|1=// some files use this
 +
# include <A/b>
 +
 +
// we prefer, to unify the coding style
 +
#include <A/b>}}
 +
 +
*coding-style-check-Space-Include.sh

Revision as of 17:32, 12 October 2013

Under construction.png
 
Under Construction
This is a new page, currently under construction!


Contents

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.

In short: Kdepim and akonadi coding style follows the Kdelibs coding style.

The rules for kdepim and akonadi

  • don't use any <TAB>s
  • Trim the lines
  • Only single empty lines should be used
  • The first line, the last line(s) may not be empty
  • Use one space after each keyword, but not after a cast
  • no "one line" if-statement

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

Check the objects

As a first approach, not any object may have binary change after applying one of the rules. To check this, one uses the Check-the-Objects.sh. Download the script: Media:Check-the-Objects.sh.gz

The script can be used with one of the commands:

  • save
  • test
  • clean

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

Check the assembler files

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.

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. Download the script: Media:Prepare-build_make_files.sh.gz

Remove the debug informations

The biggest part of the debug informations beginns with the directive line

  • .Ldebug_info0

We drop all the next lines.

We drop also the lines with the directive .loc They contain an information about the source line (here 123) we need later to drop the lines

  • movl $123, %edx
  • movl $123, %ecx

The lines with

  • .string "/home/guy-kde/projects/kdepimlibs/akonadi/agentbase.cpp:454"

will be also removed.

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:

  • save
  • test
  • clean

The scripts

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.

don't use any <TAB>s

  • coding-style-check-Tabs.sh
  • coding-style-change-Tabs.sh

Download the scripts: Media:Tabs.tar.gz

The output of the check script is:

check the file /home/guy-kde/projects/kdepimlibs/ktnef/ktnefparser.cpp
1->308: Tab at 16:   stream_ >> i;              // i <- attribute type & name
2->311: Tab at 16:   stream_ >> i;              // i <- data length
3->326: Tab at 22:   case attATTACHMENT:        // try to get attachment info
4->367: Tab at 16:   stream_ >> u;      // u <- checksum
a  b    c            d

This shows:

  • the name of the file which is under test.
  • the number of occurence(a), the line number(b), the position found(c) and the line itself(d).

The change script:

  • makes a substitution of any <TAB> with eight spaces,
  • The change works for the complete source, even within comments and strings,
  • That might be too much and changes the vertical alignment of the code.

Trim the lines

  • coding-style-check-Trim.sh
  • coding-style-change-Trim.sh

Download the scripts: Media:Trim.tar.gz

The output of the check script is:

check the file /home/guy-kde/Software/coding-style-check/trim.cpp
1->51: Space(s) at end of line (28):   QVariant m_matchData;

This shows:

  • the name of the file which is under test.
  • the number of occurence, the line number, the position found and the line itself.


The change script:

  • remove all trailing space(s).

Only single empty lines should be used

Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Whitespace

  • coding-style-check-Twice.sh
  • coding-style-change-Twice.sh

The output of the check script is:

check the file /home/guy-kde/projects/kdepimlibs/syndication/rss2/enclosure.cpp
1->25: next empty line found
2->26: next empty line found
3->30: next empty line found

This shows:

  • the name of the file which is under test.
  • the number of occurrences and the line numbers.

The change script:

  • removes all the next empty line(s).

First line, last line(s) may not be empty

Some of the sources have a first empty lines, some have one or more empty last line(s).

  • coding-style-check-First-Last.sh
  • coding-style-change-First-Last.sh

The output of the check script is:

check the file /home/guy-kde/Software/coding-style-check/trim.cpp
The first line is empty
The last line is empty

The change script:

  • removes the first line if empty, all the last empty line(s).

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

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:

  • coding-style-check-SpaceAfterKeyword.sh
  • coding-style-change-SpaceAfterKeyword.sh

For all keywords above:

  • coding-style-check-SpaceAfter.sh
  • coding-style-change-SpaceAfter.sh

The output of the check script is:

check the file /home/guy-kde/projects/kdepimlibs/akonadi/contact/contactstreemodel.cpp
1->98:  if( at 10:           if( contact.realName().isEmpty() ) {
2->99:  if( at 12:             if( contact.preferredEmail().isEmpty() ) {

The change script:

  • puts a space after the keyword.

no "one line" if-statement

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 read, 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.

  • coding-style-check-One-Line-If.sh

The output of the check script is:

check the file /home/guy-kde/Software/coding-style-check/if-example.cpp
1->25: one-line-if found

Pedantic

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

  • coding-style-check-Pedantic.sh

#include directive

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>
  • coding-style-check-Space-Include.sh

KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal