Policies/Kdepim Coding Style: Difference between revisions

    From KDE TechBase
    Line 34: Line 34:
    * clean
    * clean


    An example
    '''An example:'''


    {{Input|1=cd <some_kdepim_directory>
    {{Input|1=cd <some_kdepim_directory>

    Revision as of 16:02, 18 March 2013

     
    Under Construction
    This is a new page, currently under construction!


    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 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:

    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. The output of the check script is:

    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 first script is to check a single file or a complete directory for all .h and .cpp files.

    The scripts

    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

    The output of the check script is:

    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

    The output of the check script is:

    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:

    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:

    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).