Difference between revisions of "Policies/Kdepim Coding Style"

Jump to: navigation, search
(Check the assembler files)
(Replaced content with "{{Moved To Community}}")
 
(302 intermediate revisions by one other user not shown)
Line 1: Line 1:
{{Construction}}
+
{{Moved To Community}}
 
+
== Purpose of this document ==
+
 
+
This document describes the recommended coding style for kdepim. 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 coding style follows the''
+
[http://techbase.kde.org/Policies/Kdelibs_Coding_Style Kdelibs coding style].
+
 
+
== The rules for Kdepim ==
+
 
+
*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
+
 
+
== 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:'''
+
 
+
{{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'''
+
 
+
=== Remove the debug informations ===
+
 
+
== 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:
+
{{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:
+
*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:
+
{{Output|1=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 ====
+
 
+
*coding-style-check-Twice.sh
+
*coding-style-change-Twice.sh
+
 
+
The output of the '''check''' script is:
+
{{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:
+
*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).
+

Latest revision as of 18:19, 10 March 2016

This page is now on the community wiki.


This page was last modified on 10 March 2016, at 18:19. Content is available under Creative Commons License SA 3.0 as well as the GNU Free Documentation License 1.2 unless otherwise noted.