Policies/Kdepim Coding Style: Difference between revisions

    From KDE TechBase
    (Replaced content with "{{Moved To Community}}")
     
    (301 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.