Difference between revisions of "Policies/Kdepim Coding Style"

Jump to: navigation, search
(Created page with "<languages /> <translate> <!--T:1--> This document describes the recommended coding style for kdepim. Nobody is forced to use this style, but to have consistent formatting of ...")
 
Line 8: Line 8:
  
 
</translate>
 
</translate>
 +
{{Construction}}
 +
==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.
  
'''Under Construction'''
+
To do the migration, we are using two kinds of scripts:
 +
*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
 +
  Using <TAB> is not recommanded.
  
Rules with test and automatic changes
+
*trim the lines
 +
  No <SPACE> at the end of a line.
  
- don't use any <TAB>s
+
*no twice (or more) empty lines
   The change script makes a substitution of any <TAB> with eight spaces.
+
   The first line muss be not empty.
   The change works for the complete source, even within comments and strings.
+
   Use only one empty line.
   That might be to much and change the vertical alignment of the code.
+
   The last line muss be not empty.
- trim the lines
+
- no twice (or more) empty lines
+
  
Migration
+
==The Migration==
 
+
For each rule, one can find one or two script(s).
As discussed at KDEPIM-Treff, Berlin 3. of 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 rules, one can find one or two script(s).
+
 
The first script is to check a single file or a complete directory for all
 
The first script is to check a single file or a complete directory for all
 
.h and .cpp files.
 
.h and .cpp files.
Line 33: Line 39:
 
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 situation, the script makes no change.
+
For some complicated situations, the 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===
 +
:coding-style-check-Tabs.sh
 +
:coding-style-change-Tabs.sh
 +
The output of the check is:
 +
{{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
 +
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)</nowiki>}} 
 +
 
 +
showing:
 +
: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,
 +
  works for the complete source, even within comments and strings,
 +
  That might be too much and changes the vertical alignment of the code.
  
The scripts
+
===trim the lines===
- don't use any <TAB>s
+
:coding-style-check-Trim.sh
    coding-style-check-Tabs.sh
+
:coding-style-change-Trim.sh
    coding-style-change-Tabs.sh
+
The output of the check is:
  The output of the check is:
+
{{Output|1=<nowiki>check the file /home/guy-kde/Software/coding-style-check/trim.cpp
    /home/guy-kde/projects/kdepimlibs/ktnef/ktnefparser.cpp
+
2->51: Space(s) at end of line (28)QVariant m_matchData;</nowiki>}}
    1->308: Tab at 16:  stream_ >> i;              // i <- attribute type & name
+
showing:
    2->311: Tab at 16stream_ >> i;             // i <- data length
+
:the name of the file which is under test.
    3->326: Tab at 22:  case attATTACHMENT:        // try to get attachment info
+
:the number of occurence, the line number, the position found and the line itself.
    4->367: Tab at 16:  stream_ >> u;      // u <- checksum
+
   
+
  showing:
+
  - 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
+
The change script
    coding-style-check-Trim.sh
+
  removes all the space(s) at the end of all lines.
    coding-style-change-Trim.sh
+
  
- no twice (or more) empty lines
+
===no twice (or more) empty lines===
    coding-style-check-Twice.sh
+
:coding-style-check-Twice.sh
    coding-style-change-Twice.sh
+
:coding-style-change-Twice.sh
  The output of the check is:
+
The output of the check is:
    /home/guy-kde/projects/kdepimlibs/syndication/rss2/enclosure.cpp
+
{{Output|1=<nowiki>check the file /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
+
     3->30: next empty line found</nowiki>}}
   
+
  showing:
+
  - the name of the file which is under test.
+
  - the number of occurence and the line number.
+

Revision as of 16:24, 6 March 2013

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.

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

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

Contents

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:

  • 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
 Using <TAB> is not recommanded.
  • trim the lines
 No <SPACE> at the end of a line.
  • no twice (or more) empty lines
 The first line muss be not empty.
 Use only one empty line.
 The last line muss be not empty.

The Migration

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.

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

coding-style-check-Tabs.sh
coding-style-change-Tabs.sh

The output of the check 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)

showing:

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

check the file /home/guy-kde/Software/coding-style-check/trim.cpp
2->51: Space(s) at end of line (28):   QVariant m_matchData;

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

 removes all the space(s) at the end of all lines.

no twice (or more) empty lines

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

The output of the check 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

KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal