|
|
(312 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
| + | |
− | }}
| + | |
− | | + | |
− | === 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).
| + | |