Difference between revisions of "Policies/Kdepim Coding Style"

Jump to: navigation, search
(No twice empty lines)
(No space before a comma)
 
(257 intermediate revisions by one user not shown)
Line 1: Line 1:
{{Construction}}
 
 
 
== Purpose of this document ==
 
== Purpose of this document ==
  
Line 10: Line 8:
 
[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 and akonadi ==
+
But we have some more rules for some more situations.
  
*don't use any <TAB>s
+
== Why is coding Style useful? ==
*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 ==
+
Let us make a comparision with real life.
 +
To make an addition, one can write:
  
As discussed at the KDEPIM meeting, Berlin, 3 March 2013, all the files of KDEPIM will
+
{{Output| 1=123
be reviewed to follow the coding style.  This will be done over a long time,
+
+      456
directory after directory, for each of the
+
  ==========
rules defined above.  For each rule, one can find one or two script(s). 
+
    =      579
 +
}}
  
== Check the objects ==
+
But we have learned in primary school to write:
  
As a first approach, not any object may have binary change after applying one of the rules.
+
{{Output| 1=Addition
To check this, one uses the '''Check-the-Objects.sh'''. Download the script: [[Media:Check-the-Objects.sh.gz]]
+
  123
 +
+456
 +
====
 +
=579
 +
}}
  
The script can be used with one of the commands:
+
Which is much more readable, easy to control (or debug).
* save
+
* test
+
* clean
+
  
'''An example:'''
+
This is Coding Style: not mandatory, but very useful and pretty to read.
  
{{Input|1=cd <some_kdepim_directory>
+
== What do we need? ==
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}}
+
'''We need at least:'''
The script makes a copy of all the objects and a "time stamp":
+
*a '''specification''' (a set of rules) for the coding style of the sources
{{Output|1=save the object ./kholidays/tests/CMakeFiles/testzodiac.dir/testzodiac.cpp.o
+
*some tools to '''check the sources''' against the specification
save the object ./kholidays/tests/CMakeFiles/testzodiac.dir/testzodiac_automoc.cpp.o
+
*some tools to '''change the sources'''
...
+
all objects are saved}}
+
  
Now, one makes somes change(s) on the source(s) and:
 
  
{{Input| 1=make}}
+
[http://astyle.sourceforge.net/ astyle] is a very suitable tool to make such changes. But astyle doesn't implement (yet) all the specification rules.
  
Depending on the Makefile, some objects will be compiled again:
+
You can find below some awk-scripts which help us to check all the rules.
  
{{Output| 1=<span style="color:Fuchsia">Scanning dependencies of target akonadi-kde</span>
+
You can find below some awk-scripts which help us to make most of the changes.
[ 17%] <span style="color:green">Building CXX object akonadi/CMakeFiles/akonadi-kde.dir/entitytreeview.cpp.o</span>
+
The last part must be done manually.
[ 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 specification rules of coding style for kdepim and akonadi ==
  
The script finds all the new objects, makes a comparision with the saved version:
+
These are the sub-sections under '''The rules and the scripts ...'''
{{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 ==
+
== Migration ==
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 }).
+
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).
  
For this reason it is no more possible to compare the objects.
+
The main part of the changes can be done with astyle:
We have to compare the assembler files.
+
http://astyle.sourceforge.net/
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 ===
+
The results can be seen [http://techbase.kde.org/ResultsOfTheMigration here].
  
To generate the assembler files, we only need to modify the ''build.make'' in every folder.
+
== Download Coding Style ==
  
The script '''Prepare-build_make_files.sh''' works on the all directory, finds the line with the compiler command,
+
You can download the software with test files and install instructions.
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 ===
+
Download Coding Style: [[Media:CodingStyle.tar.gz]]
  
The biggest part of the debug informations beginns with the directive line
+
== Two scripts '''to check all the rules''' and '''to make the all the changes''' ==
*.Ldebug_info0
+
We drop all the next lines.
+
  
We drop also the lines with the directive .loc
+
Most of the rules can be checked with the scripts below.
They contain an information about the source line (here 123) we need later to drop the lines
+
For some of the rules, we don't have a script to change the sources.
* movl $123, %edx
+
It is better first to make a check for such a rule, second to make the modification(s) manually to suscript the rule(s).
* movl $123, %ecx
+
  
The lines with
+
There are two scripts that run all the checks and apply all the changes at once:
* .string "/home/guy-kde/projects/kdepimlibs/akonadi/agentbase.cpp:454"
+
*All-Check.sh
will be also removed.
+
*Change-All.sh
  
The script to check the assembler files can be used in the same way as the one above (Check-the-Objects.sh).
+
For each specification rule, the name of the scripts to check and apply the changes
To check this, one uses the '''Check-the-assembler_code.sh'''. Download the script: [[Media:Check-the-assembler_code.sh.gz]]
+
are given at the beginning of the section.
  
The script can be used with one of the commands:
+
== The rules and the scripts '''to check''' and '''to make the changes''' ==
* save
+
* test
+
* clean
+
  
== The scripts ==
+
The first script is '''to check''' a single file or all .h and .cpp files in a directory.
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
+
If present, the second script '''applies the changes'''.
directory for all .h and .cpp files.  For some complicated situations, the
+
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.
+
You can use the scripts for your own work. It is recommended to use them in this order.
  
==== don't use any <TAB>s ====
+
=== Don't test all directories ===
*coding-style-check-Tabs.sh
+
*coding-style-change-Tabs.sh
+
  
Download the scripts: [[Media:Tabs.tar.gz]]
+
If a '''.no_coding_style''' file is present on a directory, the test will not be done.
  
The output of the '''check''' script is:
+
If a '''.no_recursion''' file is present on a directory, we do not explore the subdirectory(ies)
{{Output|1=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:
+
=== Indentation with four spaces, don't use any <TAB>s ===
*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 ====
+
*Tabs-check.sh
 +
*Tabs.awk
 +
*The changes are well done with
 +
{{Output| 1=astyle --indent=spaces=4
 +
}}
  
*coding-style-check-Trim.sh
+
=== Trim the lines ===
*coding-style-change-Trim.sh
+
  
Download the scripts: [[Media:Trim.tar.gz]]
+
*Trim-check.sh
 +
*Trim.awk
 +
*The changes are well done with:
 +
{{Output| 1=astyle --indent=spaces
 +
}}
  
The output of the '''check''' script is:
+
=== Only single empty lines ===
{{Output|1=check the file /home/guy-kde/Software/coding-style-check/trim.cpp
+
Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Whitespace
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.
+
  
 +
*Twice-check.sh
 +
*Twice-change.sh
 +
*Twice.awk
  
The '''change''' script:
+
=== The first line and the last line(s) may not be empty ===
*remove all trailing space(s).
+
  
==== Only single empty lines should be used ====
+
Some of the sources have empty lines at the beginning of the file. Some have one or more empty last line(s).
Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Whitespace
+
*First-check.sh
 +
*First-change.sh
 +
*First.awk
  
*coding-style-check-Twice.sh
+
=== Only one statement per line ===
*coding-style-change-Twice.sh
+
  
The output of the '''check''' script is:
+
We don't provide (yet) any check for this rule.
{{Output|1=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:
+
=== Variable declaration ===
*removes all the next empty line(s).
+
  
==== First line, last line(s) may not be empty ====
+
We follow the kdelibs rule: [[http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Variable_declaration]]
 +
We don't provide (yet) any check for this rule.
  
Some of the sources have a first empty lines, some have one or more empty last line(s).
+
=== Only one declaration per line ===
*coding-style-check-First-Last.sh
+
*coding-style-change-First-Last.sh
+
  
The output of the '''check''' script is:
+
We follow the kdelibs rule: [[http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Variable_declaration]]
{{Output|1=check the file /home/guy-kde/Software/coding-style-check/trim.cpp
+
We don't provide (yet) any check for this rule.
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 ====
+
=== Use one space after each keyword, but not after a cast ===
  
 
Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Whitespace
 
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:
+
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 compiled source:
{{Output|1=inta;
+
{{Output|1=intmyVariableAa;
floatb;}}
+
floatmyVariableBb;}}
 +
 
 +
In this case, the missing space leads to a syntax error which is detected by the compiler. We don't need to check this manually.
  
 
Some of the keywords are alone in the statement, such as '''break''' and '''continue'''. No test is necessary.
 
Some of the keywords are alone in the statement, such as '''break''' and '''continue'''. No test is necessary.
Line 221: Line 159:
  
 
These are:
 
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'''
+
'''alignas decltype alignof noexcept typeid asm static_assert switch if catch while for foreach sizeof new Q_FOREACH 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:
+
*SpaceAfter-check.sh
*coding-style-check-SpaceAfterKeyword.sh
+
*SpaceAfter-change.sh
*coding-style-change-SpaceAfterKeyword.sh
+
*SpaceAfter.awk
  
For '''all''' keywords above:
+
=== Use a space after the name of the class ===
*coding-style-check-SpaceAfter.sh
+
*coding-style-change-SpaceAfter.sh
+
  
The output of the '''check''' script is:
+
We prefer having a space before the keyword public at the definition of a new class:
{{Output|1=check the file /home/guy-kde/projects/kdepimlibs/akonadi/contact/contactstreemodel.cpp
+
{{Output|1=class DbException : public Akonadi::Exception
1->98:  if( at 10:          if( contact.realName().isEmpty() ) {
+
{
2->99:  if( at 12:            if( contact.preferredEmail().isEmpty() ) {
+
  ...
 +
};}}
 +
 
 +
*Public-check.sh
 +
*Public-change.sh
 +
*Public.awk
 +
 
 +
=== #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>}}
 +
 
 +
*Space-Include-check.sh
 +
*SpaceInclude.awk
 +
 
 +
=== Place '''*''' and '''&''' next to the variable ===
 +
 
 +
The declaration S *D; declares D as a pointer to the type determined by decl-specifier-seq S.
 +
 
 +
For most compilers, the three declarations below are semantically the same:
 +
 
 +
{{Output|1=int *a;
 +
int* b;
 +
int * c
 
}}
 
}}
  
The '''change''' script:
+
We prefer the first one, without a space beetwen the star and the name of the variable:
*puts a space after the keyword.
+
  
====no "one line" if-statement====
+
{{Output|1=int *a;
 +
}}
 +
 
 +
The same rule may be use for:
 +
 
 +
{{Output|1=myFunction(int &a, int& b, int & c)
 +
{
 +
    // some lines
 +
}
 +
}}
 +
 
 +
We prefer:
 +
{{Output|1=myFunction(int &a, int &b, int &c)
 +
}}
 +
 
 +
The awk-script checks also the occurences of:
 +
* '''&,'''
 +
* '''& >'''
 +
* '''* >'''
 +
* '''( )''' and '''(  )''' ''empty function call''
 +
 
 +
* '''enum {''' ''untyped enum''
 +
 
 +
Not all the ouputs are real errors. Some codings might be correct.
 +
 
 +
*NoSpace-check.sh
 +
*NoSpace.awk
 +
*using astyle to make the changes:
 +
{{Output| 1=astyle --reference=name --align-pointer=name
 +
}}
 +
 
 +
 
 +
Some lines with must be manually corrected.
 +
 
 +
=== Use '''namespace foo {''' in the same line ===
 +
 
 +
We prefer having all in one line:
 +
{{Output|1=namespace foo {
 +
  ...
 +
}
 +
}}
 +
 
 +
*Namespace-check.sh
 +
*Namespace.awk
 +
*astyle to make the changes.
 +
 
 +
=== Use '''struct foo''' with '''{''' at the next line ===
 +
 
 +
We prefer having the same coding style for a '''class''' and a '''struct'''
 +
{{Output|1=struct foo
 +
{
 +
  ...
 +
}
 +
}}
 +
 
 +
*Struct-check.sh
 +
*Struct-change.sh
 +
*Struct.awk
 +
 
 +
NOTE: The script must be use after astyle.
 +
 
 +
=== Each member initialization of a method in separate line ===
 +
 
 +
This example shows the indentation we prefer. Notice that colon sign and comma(s)
 +
are at the beginning of each initialization line(s):
 +
 
 +
{{Output|1=class myClass
 +
{
 +
    // some lines
 +
public:
 +
    myClass(int r, int b, int i, int j)
 +
        : r(0)
 +
        , b(i)
 +
        , i(5)
 +
        , j(13)
 +
{
 +
    // more lines
 +
}
 +
};
 +
}}
 +
 
 +
*Default-check.sh
 +
*Default-change.sh
 +
*Default.awk
 +
 
 +
=== Surround all operators with spaces ===
 +
 
 +
This is well done with astyle:
 +
{{Output| 1=astyle --pad-oper
 +
}}
 +
 
 +
=== '''switch''' rules ===
 +
 
 +
This example shows the indentation we prefer:
 +
 
 +
{{Output|1=switch (a) {
 +
case ''one'':
 +
    // some lines
 +
    break;
 +
case ''two'': {
 +
    // some lines
 +
    break;
 +
}
 +
case ''three'': {
 +
    // some lines
 +
    return;
 +
}
 +
default:
 +
    // some lines
 +
    break;
 +
}
 +
}}
 +
 
 +
*Switch-check.sh
 +
*Switch.awk
 +
*astyle makes the changes
 +
 
 +
NOTE: By using a new block, we prefer having '''break;''' and '''return;''' within the new block.
 +
 
 +
=== '''try-catch''' rules ===
 +
 
 +
This example shows the indentation we prefer:
 +
 
 +
{{Output|1=try {
 +
    // some lines
 +
} catch (...) {
 +
}
 +
}}
 +
 
 +
*TryCatch-check.sh
 +
*TryCatch.awk
 +
 
 +
=== '''if''', '''else''', '''for''', '''while''' (and similar macros) rules ===
 +
 
 +
Even for blocks with only one statement, we prefer to use braces such as:
 +
 
 +
{{Output|1=if (''condition'') {
 +
    ''statement;''
 +
}
 +
}}
 +
 
 +
This should be used with the keywords '''if''', '''else''', '''for''', '''while''' and similar macros.
 +
 
 +
*If-check.sh
 +
*Else-check.sh
 +
*For-check.sh
 +
*While-check.sh
 +
*If.awk
 +
*Else.awk
 +
*For.awk
 +
*While.awk
 +
*astyle makes the changes.
 +
 
 +
 
 +
But we get some false alarm with statements that extend over more than one line:
 +
 
 +
{{Output|1=if (''condition_1''
 +
    && ''condition_2'') {
 +
    ''statement;''
 +
}
 +
}}
 +
 
 +
=== '''typedef struct''' statement over more lines ===
 +
 
 +
This example shows the indentation we prefer:
 +
 
 +
{{Output|1=typedef struct foo {
 +
    // some lines
 +
}
 +
}}
 +
 
 +
*TypedefStruct-check.sh
 +
*TypeStruct.awk
 +
 
 +
=== Don't use '''&''' without a variable ===
 +
 
 +
It is more readable to have the name of (all) the variable(s) in the first line of a method.
 +
 
 +
The chnages must be done manually.
 +
 
 +
=== Don't use untyped '''enum''' ===
 +
 
 +
Instead of having an untyped enum such as:
 +
{{Output|1=  enum {
 +
    aElement= 123
 +
}
 +
}}
 +
we prefer a #define directive:
 +
{{Output|1=#define aElement 123
 +
}}
 +
 
 +
=== Don't use '''enum''' with empty member ===
 +
 
 +
The most compilers do not complain such a code:
 +
 
 +
{{Output|1=  enum mytype {
 +
    aElement,
 +
    bElement,
 +
}
 +
}}
 +
 
 +
The last element is empty.
 +
We prefer a "pedantic" code such as:
 +
 
 +
{{Output|1=  enum mytype {
 +
    aElement,
 +
    bElement
 +
}
 +
}}
 +
 
 +
*EnumPedantic-check.sh
 +
*EnumPedantic.awk
 +
 
 +
=== 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'''
 +
 
 +
*Pedantic-check.sh
 +
*Pedantic.awk
 +
 
 +
=== No "one line" '''if''', '''else''', '''for''' or '''while''' statement ===
  
 
Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Braces
 
Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Braces
  
 
The following code:
 
The following code:
{{Output|1=if ( a > b ) c = 123;}}
+
{{Output|1=if (a > b) c = 123;}}
 
is correct, but we prefer the block:
 
is correct, but we prefer the block:
{{Output|1=if ( a > b ) {
+
{{Output|1=if (a > b) {
 
   c = 123;
 
   c = 123;
} }}
+
}
which is easier to read, to modify.
+
}}
 +
which is easier to debug, to read and to modify.
  
 
It is also possible to put a breakpoint at the line in the block.
 
It is also possible to put a breakpoint at the line in the block.
Line 257: Line 447:
 
we can't make the changes automatically.
 
we can't make the changes automatically.
  
*coding-style-check-One-Line-If.sh
+
*OneLine-If.sh
 +
*OneLine-Else.sh
 +
*If.awk
 +
*Else.awk
  
The output of the '''check''' script is:
+
=== No space between some keywords ===
{{Output|1=check the file /home/guy-kde/Software/coding-style-check/if-example.cpp
+
1->25: one-line-if found}}
+
  
====Pedantic====
+
We don't want to have a space:
 +
*between '''&''' and '''>'''
 +
*between '''*''' and '''>'''
 +
*between '''(''' and ''')''', an empty parameter list.
  
Looking over the git-history, one can find some "pedantic" changes.
+
*NoSpace-check.sh
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.
+
*NoSpace.awk
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
+
=== No space around the index of an array ===
  
====#include directive====
+
We don't want to have spaces around the index of an array element.
  
Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Qt_Includes
+
*SpaceInArray-check.sh
 +
*SpaceInArray-change.sh
 +
*SpaceInArray.awk
  
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.
+
=== No space around an expression surrounded with braces ===
  
{{Output|1=// some files use this
+
We prefer function definition and function call with no space after the opening brace and before the closing brace.
# include <A/b>
+
  
// we prefer, to unify the coding style
+
*Parenthesis-check.sh
#include <A/b>}}
+
*Parenthesis.awk
 +
*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.
 +
*ParenthesisAlone-check.sh
 +
*ParenthesisAlone.awk
 +
 
 +
=== No space before a comma ===
 +
 
 +
This is sometime to be found in a function call.
 +
 
 +
*SpaceComma-check.sh
 +
*SpaceComma.awk
 +
 
 +
=== Operator overloading ===
 +
 
 +
As written at:
 +
 
 +
http://www.drbio.cornell.edu/pl47/programming/TICPP-2nd-ed-Vol-one-html/Chapter12.html
 +
 
 +
"... Defining an overloaded operator is like defining a function, but the name of that function is operator@, in which @ represents the operator that’s being overloaded. ..."
 +
 
 +
Some sources use a space after the reserved word operator. We prefer to use the syntax without space.
 +
 
 +
*Operator-check.sh
 +
*Operator-change.sh
 +
*Operator.awk
 +
 
 +
== 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 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 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'''.
 +
 
 +
The script can be used with one of the commands:
 +
* save
 +
* test
 +
* clean
 +
 
 +
== The results of the migration ==
  
*coding-style-check-Space-Include.sh
+
The results can be seen [http://techbase.kde.org/ResultsOfTheMigration here].

Latest revision as of 17:56, 4 November 2014

Contents

[edit] 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.

But we have some more rules for some more situations.

[edit] 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.

[edit] 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 very 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.

[edit] The specification rules of coding style for kdepim and akonadi

These are the sub-sections under The rules and the scripts ...

[edit] 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).

The main part of the changes can be done with astyle: http://astyle.sourceforge.net/

The results can be seen here.

[edit] Download Coding Style

You can download the software with test files and install instructions.

Download Coding Style: Media:CodingStyle.tar.gz

[edit] 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.

[edit] The rules and 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.

[edit] 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)

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

  • Tabs-check.sh
  • Tabs.awk
  • The changes are well done with
astyle --indent=spaces=4

[edit] Trim the lines

  • Trim-check.sh
  • Trim.awk
  • The changes are well done with:
astyle --indent=spaces

[edit] Only single empty lines

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

  • Twice-check.sh
  • Twice-change.sh
  • Twice.awk

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

Some of the sources have empty lines at the beginning of the file. Some have one or more empty last line(s).

  • First-check.sh
  • First-change.sh
  • First.awk

[edit] Only one statement per line

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

[edit] Variable declaration

We follow the kdelibs rule: [[1]] We don't provide (yet) any check for this rule.

[edit] Only one declaration per line

We follow the kdelibs rule: [[2]] We don't provide (yet) any check for this rule.

[edit] 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 compiled source:

intmyVariableAa;
floatmyVariableBb;

In this case, the missing space leads to a syntax error which is detected by the compiler. We don't need to check this manually.

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 foreach sizeof new Q_FOREACH FOREACH do try enum union Q_FOREVER bool char char16_t char32_t double float int long wchar_t signed unsigned short

  • SpaceAfter-check.sh
  • SpaceAfter-change.sh
  • SpaceAfter.awk

[edit] Use a space after the name of the class

We prefer having a space before the keyword public at the definition of a new class:

class DbException : public Akonadi::Exception
{
  ...
};
  • Public-check.sh
  • Public-change.sh
  • Public.awk

[edit] #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>
  • Space-Include-check.sh
  • SpaceInclude.awk

[edit] Place * and & next to the variable

The declaration S *D; declares D as a pointer to the type determined by decl-specifier-seq S.

For most compilers, the three declarations below are semantically the same:

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:

  • &,
  • & >
  • * >
  • ( ) and ( ) empty function call
  • enum { untyped enum

Not all the ouputs are real errors. Some codings might be correct.

  • NoSpace-check.sh
  • NoSpace.awk
  • using astyle to make the changes:
astyle --reference=name --align-pointer=name


Some lines with must be manually corrected.

[edit] Use namespace foo { in the same line

We prefer having all in one line:

namespace foo {
  ...
}
  • Namespace-check.sh
  • Namespace.awk
  • astyle to make the changes.

[edit] Use struct foo with { at the next line

We prefer having the same coding style for a class and a struct

struct foo
{
  ...
}
  • Struct-check.sh
  • Struct-change.sh
  • Struct.awk

NOTE: The script must be use after astyle.

[edit] Each member initialization of a method in separate line

This example shows the indentation we prefer. Notice that colon sign and comma(s) are at the beginning of each initialization line(s):

class myClass
{
    // some lines
public:
    myClass(int r, int b, int i, int j)
        : r(0)
        , b(i)
        , i(5)
        , j(13)
{
    // more lines
}
};
  • Default-check.sh
  • Default-change.sh
  • Default.awk

[edit] Surround all operators with spaces

This is well done with astyle:

astyle --pad-oper

[edit] switch rules

This example shows the indentation we prefer:

switch (a) {
case one:
    // some lines
    break;
case two: {
    // some lines
    break;
}
case three: {
    // some lines
    return;
}
default:
    // some lines
    break;
}
  • Switch-check.sh
  • Switch.awk
  • astyle makes the changes

NOTE: By using a new block, we prefer having break; and return; within the new block.

[edit] try-catch rules

This example shows the indentation we prefer:

try {
    // some lines
} catch (...) {
}
  • TryCatch-check.sh
  • TryCatch.awk

[edit] if, else, 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, else, for, while and similar macros.

  • If-check.sh
  • Else-check.sh
  • For-check.sh
  • While-check.sh
  • If.awk
  • Else.awk
  • For.awk
  • While.awk
  • astyle makes the changes.


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

if (condition_1
    && condition_2) {
    statement;
}

[edit] typedef struct statement over more lines

This example shows the indentation we prefer:

typedef struct foo {
    // some lines
}
  • TypedefStruct-check.sh
  • TypeStruct.awk

[edit] Don't use & without a variable

It is more readable to have the name of (all) the variable(s) in the first line of a method.

The chnages must be done manually.

[edit] Don't use untyped enum

Instead of having an untyped enum such as:

enum {
    aElement= 123
}

we prefer a #define directive:

#define aElement 123

[edit] 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
}
  • EnumPedantic-check.sh
  • EnumPedantic.awk

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

  • Pedantic-check.sh
  • Pedantic.awk

[edit] No "one line" if, else, for or while 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 debug, to 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.

  • OneLine-If.sh
  • OneLine-Else.sh
  • If.awk
  • Else.awk

[edit] No space between some keywords

We don't want to have a space:

  • between & and >
  • between * and >
  • between ( and ), an empty parameter list.
  • NoSpace-check.sh
  • NoSpace.awk

[edit] No space around the index of an array

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

  • SpaceInArray-check.sh
  • SpaceInArray-change.sh
  • SpaceInArray.awk

[edit] 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.

  • Parenthesis-check.sh
  • Parenthesis.awk
  • 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

[edit] No space before : in a case statement

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

[edit] No space before ; at the end of statement

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

[edit] No ); alone in a line

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

  • ParenthesisAlone-check.sh
  • ParenthesisAlone.awk

[edit] No space before a comma

This is sometime to be found in a function call.

  • SpaceComma-check.sh
  • SpaceComma.awk

[edit] Operator overloading

As written at:

http://www.drbio.cornell.edu/pl47/programming/TICPP-2nd-ed-Vol-one-html/Chapter12.html

"... Defining an overloaded operator is like defining a function, but the name of that function is operator@, in which @ represents the operator that’s being overloaded. ..."

Some sources use a space after the reserved word operator. We prefer to use the syntax without space.

  • Operator-check.sh
  • Operator-change.sh
  • Operator.awk

[edit] Use all the scripts

All the scripts can be used with one only script.

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

[edit] 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.

[edit] 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.

[edit] 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.

The script can be used with one of the commands:

  • save
  • test
  • clean

[edit] The results of the migration

The results can be seen here.


This page was last modified on 4 November 2014, at 17:56. This page has been accessed 27,143 times. Content is available under Creative Commons License SA 3.0 as well as the GNU Free Documentation License 1.2.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal