Policies/Kdepim Coding Style: Difference between revisions

    From KDE TechBase
    No edit summary
    No edit summary
    Line 1: Line 1:
    <languages />
    {{Construction}}
    <translate>
     
    <!--T:1-->
    == 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 strengly recommended to make use of it.


    <!--T:2-->
    This document describes the recommended coding style for kdepim. Nobody is
    '''In short: Kdepim coding style follows the [http://techbase.kde.org/Policies/Kdelibs_Coding_Style Kdelibs coding style].'''
    forced to use this style, but to have consistent formatting of the source code
    files it is strongly recommended to make use of it.


    </translate>
    {{Remember|1=In short: Kdepim coding style follows the
    {{Construction}}
    [http://techbase.kde.org/Policies/Kdelibs_Coding_Style Kdelibs coding style].}}
    ==Introduction==
    As discussed at the KDEPIM meeting, Berlin 3. of march 2013, all the files of KDEPIM
    will be reviewed to follow the coding style.
    Not all the kdepim-sources follows yet ( 6 Mar 2013 ) these rules.
    A migration is actually running, directory after directory, for each of the
    rules defined under. But it's still needs some more weeks to be ready.


    To do the migration, we are using two kinds of scripts:
    == Rules with test and automatic changes ==
    *to check the sources,
    *to change the sources automatically if possible. It is sometime advice to modify the result of the second script.


    ==The rules==
    *don't use any <TAB>s
    *don't use any <TAB>s
      Using <TAB> is not recommanded.
    *The change script makes a substitution of any <TAB> with eight spaces.
     
    *The change works for the complete source, even within comments and strings.
    *trim the lines
    *That might be too much and change the vertical alignment of the code.
      No <SPACE> at the end of a line.
    *Trim the lines
    *Only single empty lines should be used.


    *no twice (or more) empty lines
    == Migration ==
      The first line muss be not empty.
      Use only one empty line.
      The last line muss be not empty.


    ==The Migration==
    As discussed at KDEPIM-Treff, Berlin, 3 March 2013, all the files of KDEPIM will
    For each rule, one can find one or two script(s).
    be reviewed to follow the coding style.  This will be done over a long time,
    The first script is to check a single file or a complete directory for all
    directory after directory, for each of the
    .h and .cpp files.
    rules defined above.  For each rule, one can find one or two script(s). 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
    If present, the second script makes the changes for a single file or a complete
    directory for all .h and .cpp files.
    directory for all .h and .cpp files. For some complicated situations, the
    For some complicated situations, the script makes no change.
    script makes no change.


    One can use the scripts for it's own work. It is important to use them in the shown order.
    === The scripts ===
     
    *don't use any <TAB>s
    ==The scripts==
    *coding-style-check-Tabs.sh
    ===don't use any <TAB>s===
    *coding-style-change-Tabs.sh
    :coding-style-check-Tabs.sh
    *The output of the check is:
    :coding-style-change-Tabs.sh
    {{Output|<syntaxhighlight lang="php" line>
    The output of the check is:
    /home/guy-kde/projects/kdepimlibs/ktnef/ktnefparser.cpp
    {{Output|1=<nowiki>check the file /home/guy-kde/projects/kdepimlibs/ktnef/ktnefparser.cpp
    1->308: Tab at 16:  stream_ >> i;              // i <- attribute type & name
    1->308: Tab at 16:  stream_ >> i;              // i <- attribute type & name
    2->311: Tab at 16:  stream_ >> i;              // i <- data length
    2->311: Tab at 16:  stream_ >> i;              // i <- data length
    3->326: Tab at 22:  case attATTACHMENT:        // try to get attachment info
    3->326: Tab at 22:  case attATTACHMENT:        // try to get attachment info
    4->367: Tab at 16:  stream_ >> u;      // u <- checksum
    4->367: Tab at 16:  stream_ >> u;      // u <- checksum
    (a) (b)      (c)    (d)</nowiki>}}   
    </syntaxhighlight>}}
        
    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.


    showing:
    === Trim the lines ===
    :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
    {{Input| <syntaxhighlight lang="php" line>
      makes a substitution of any <TAB> with eight spaces,
        coding-style-check-Trim.sh
      works for the complete source, even within comments and strings,
        coding-style-change-Trim.sh
      That might be too much and changes the vertical alignment of the code.
    </syntaxhighlight>}}


    ===trim the lines===
    === Check for multiple empty lines ===
    :coding-style-check-Trim.sh
    :coding-style-change-Trim.sh
    The output of the check is:
    {{Output|1=<nowiki>check the file /home/guy-kde/Software/coding-style-check/trim.cpp
    2->51: Space(s) at end of line (28):  QVariant m_matchData;</nowiki>}}
    showing:
    :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
    {{Input| <syntaxhighlight lang="php" line>
      removes all the space(s) at the end of all lines.
        coding-style-check-Twice.sh
        coding-style-change-Twice.sh
    </syntaxhighlight>}}


    ===no twice (or more) empty lines===
    :coding-style-check-Twice.sh
    :coding-style-change-Twice.sh
    The output of the check is:
    The output of the check is:
    {{Output|1=<nowiki>check the file /home/guy-kde/projects/kdepimlibs/syndication/rss2/enclosure.cpp
    {{Output| <syntaxhighlight lang="php" line>
        /home/guy-kde/projects/kdepimlibs/syndication/rss2/enclosure.cpp
         1->25: next empty line found
         1->25: next empty line found
         2->26: next empty line found
         2->26: next empty line found
         3->30: next empty line found</nowiki>}}
         3->30: next empty line found
    </syntaxhighlight>}}
       
    This shows:
    * the name of the file which is under test.
    * the number of occurrences and the line numbers.

    Revision as of 15:42, 6 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.

     
    Remember
    In short: Kdepim coding style follows the Kdelibs coding style.


    Rules with test and automatic changes

    • don't use any <TAB>s
    • 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 change the vertical alignment of the code.
    • Trim the lines
    • Only single empty lines should be used.

    Migration

    As discussed at KDEPIM-Treff, 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). 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.

    The scripts

    • don't use any <TAB>s
    • coding-style-check-Tabs.sh
    • coding-style-change-Tabs.sh
    • The output of the check is:
    /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
    

    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.

    Trim the lines

     
        coding-style-check-Trim.sh
        coding-style-change-Trim.sh
    

    Check for multiple empty lines

     
        coding-style-check-Twice.sh
        coding-style-change-Twice.sh
    

    The output of the check is:

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