|
|
| (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).
| + | |
KDE TechBase 