Policies/Kdepim Coding Style: Difference between revisions

    From KDE TechBase
    (166 intermediate revisions by the same user not shown)
    Line 8: Line 8:
    [http://techbase.kde.org/Policies/Kdelibs_Coding_Style Kdelibs coding style].
    [http://techbase.kde.org/Policies/Kdelibs_Coding_Style Kdelibs coding style].


    == The rules for kdepim and akonadi ==
    But we have some more rules for some more situations.


    *don't use any <TAB>s
    == Why is coding Style useful? ==
    *Trim the lines
     
    *Only single empty lines should be used
    Let us make a comparision with real life.
    *The first line, the last line(s) may not be empty
    To make an addition, one can write:
    *Use one space after each keyword, but not after a cast
     
    *no "one line" if-statement
    {{Output| 1=123
    +      456
      ==========
        =      579
    }}
     
    But we have learned in primary school to write:
     
    {{Output| 1=Addition
      123
    +456
    ====
    =579
    }}
     
    Which is much more readable, easy to control (or debug).
     
    This is Coding Style: not mandatory, but very useful and pretty to read.
     
    == What do we need? ==
     
    '''We need at least:'''
    *a '''specification''' (a set of rules) for the coding style of the sources
    *some tools to '''check the sources''' against the specification
    *some tools to '''change the sources'''
     
     
    [http://astyle.sourceforge.net/ astyle] is a very suitable tool to make such changes. But astyle doesn't implement (yet) all the specification rules.
     
    You can find below some awk-scripts which help us to check all the rules.
     
    You can find below some awk-scripts which help us to make most of the changes.
    The last part must be done manually.
     
    == The specification rules of coding style for kdepim and akonadi ==
     
    These are the sub-sections under '''The rules and the scripts ...'''


    == Migration ==
    == Migration ==
    Line 22: Line 58:
    be reviewed to follow the coding style.  This will be done over a long time,
    be reviewed to follow the coding style.  This will be done over a long time,
    directory after directory, for each of the
    directory after directory, for each of the
    rules defined above.  For each rule, one can find one or two script(s).
    rules defined above.  For each rule, there are one or two script(s).


    The main part of the changes can be done with astyle:
    The main part of the changes can be done with astyle:
    http://astyle.sourceforge.net/
    http://astyle.sourceforge.net/


    == Check the objects ==
    The results can be seen [http://techbase.kde.org/ResultsOfTheMigration here].
     
    == Download Coding Style ==


    As a first approach, not any object may have binary change after applying one of the rules.
    You can download the software with test files and install instructions.
    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:
    Download Coding Style: [[Media:CodingStyle.tar.gz]]
    * save
     
    * test
    == Two scripts '''to check all the rules''' and '''to make the all the changes''' ==
    * clean
     
    Most of the rules can be checked with the scripts below.
    For some of the rules, we don't have a script to change the sources.
    It is better first to make a check for such a rule, second to make the modification(s) manually to suscript the rule(s).
     
    There are two scripts that run all the checks and apply all the changes at once:
    *All-Check.sh
    *Change-All.sh
     
    For each specification rule, the name of the scripts to check and apply the changes
    are given at the beginning of the section.
     
    == The rules and the scripts '''to check''' and '''to make the changes''' ==
     
    The first script is '''to check''' a single file or all .h and .cpp files in a directory.


    '''An example:'''
    If present, the second script '''applies the changes'''.
    For some complicated situations, the script makes no change.


    {{Input|1=cd <some_kdepim_directory>
    You can use the scripts for your own work. It is recommended to use them in this order.
    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}}
    === Don't test all directories ===
    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:
    If a '''.no_coding_style''' file is present on a directory, the test will not be done.


    {{Input| 1=make}}
    If a '''.no_recursion''' file is present on a directory, we do not explore the subdirectory(ies)


    Depending on the Makefile, some objects will be compiled again:
    === Indentation with four spaces, don't use any <TAB>s ===


    {{Output| 1=<span style="color:Fuchsia">Scanning dependencies of target akonadi-kde</span>
    *Tabs-check.sh
    [ 17%] <span style="color:green">Building CXX object akonadi/CMakeFiles/akonadi-kde.dir/entitytreeview.cpp.o</span>
    *Tabs.awk
    [ 17%] <span style="color:green">Building CXX object akonadi/CMakeFiles/akonadi-kde.dir/itemfetchjob.cpp.o</span>
    *The changes are well done with
    [ 17%] <span style="color:green">Building CXX object akonadi/CMakeFiles/akonadi-kde.dir/statisticsproxymodel.cpp.o</span>
    {{Output| 1=astyle --indent=spaces=4
    ...
    }}
    <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}}
    === Trim the lines ===


    The script finds all the new objects, makes a comparision with the saved version:
    *Trim-check.sh
    {{Output|1=test the object ./akonadi/CMakeFiles/akonadi-kde.dir/statisticsproxymodel.cpp.o
    *Trim.awk
    test the object ./akonadi/CMakeFiles/akonadi-kde.dir/entitytreeview.cpp.o
    *The changes are well done with:
    test the object ./akonadi/CMakeFiles/akonadi-kde.dir/itemfetchjob.cpp.o
    {{Output| 1=astyle --indent=spaces
    test the object ./akonadi/kmime/CMakeFiles/akonadi-kmime.dir/standardmailactionmanager.cpp.o
    all tests are OK
    }}
    }}


    == Check the assembler files ==
    === Only single empty lines ===
    If we add or remove some lines, the debug informations included in the object file will be change also.
    Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Whitespace
     
    *Twice-check.sh
    *Twice-change.sh
    *Twice.awk
     
    === The first line and the last line(s) may not be empty ===
     
    Some of the sources have empty lines at the beginning of the file. Some have one or more empty last line(s).
    *First-check.sh
    *First-change.sh
    *First.awk
     
    === Only one statement per line ===
     
    We don't provide (yet) any check for this rule.
     
    === Variable declaration ===
     
    We follow the kdelibs rule: [[http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Variable_declaration]]
    We don't provide (yet) any check for this rule.
     
    === Only one declaration per line ===
     
    We follow the kdelibs rule: [[http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Variable_declaration]]
    We don't provide (yet) any check for this rule.
     
    === Use one space after each keyword, but not after a cast ===
     
    Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Whitespace
     
    For most of the keywords, it is not necessary to make a test. Because the sources have been already compiled. For example this code never appear in a compiled source:
    {{Output|1=intmyVariableAa;
    floatmyVariableBb;}}


    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 }).
    In this case, the missing space leads to a syntax error which is detected by the compiler. We don't need to check this manually.


    For this reason it is no more possible to compare the objects.
    Some of the keywords are alone in the statement, such as '''break''' and '''continue'''. No test is necessary.
    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 ===
    The only tests we have to do are the ones where a keyword is (or can be) followed
    by a sign '''( { [ :'''


    To generate the assembler files, we only need to modify the ''build.make'' in every folder.
    These are:
    '''alignas decltype alignof noexcept typeid asm static_assert switch if catch while for foreach sizeof new Q_FOREACH FOREACH do try enum union Q_FOREVER bool char char16_t char32_t double float int long wchar_t signed unsigned short'''


    The script '''Prepare-build_make_files.sh''' works on the all directory, finds the line with the compiler command,
    *SpaceAfter-check.sh
    duplicates the line, add a ''-S option'' and changes the name of the output to ''somename.s''.
    *SpaceAfter-change.sh
    After a new ''make'' command, we can save all the assembler files with the script '''Check-the-assembler_code.sh'''.
    *SpaceAfter.awk
    Download the script: [[Media:Prepare-build_make_files.sh.gz]]


    === Remove the debug informations ===
    === Use a space after the name of the class ===


    The biggest part of the debug informations beginns with the directive line
    We prefer having a space before the keyword public at the definition of a new class:
    *.Ldebug_info0
    {{Output|1=class DbException : public Akonadi::Exception
    We drop all the next lines.
    {
      ...
    };}}


    We drop also the lines with the directive .loc
    *Public-check.sh
    They contain an information about the source line (here 123) we need later to drop the lines
    *Public-change.sh
    * movl $123, %edx
    *Public.awk
    * movl $123, %ecx


    The lines with
    === #include directive ===
    * .string "/home/guy-kde/projects/kdepimlibs/akonadi/agentbase.cpp:454"
    will be also removed.


    The script to check the assembler files can be used in the same way as the one above (Check-the-Objects.sh).
    Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Qt_Includes
    To check this, one uses the '''Check-the-assembler_code.sh'''. Download the script: [[Media:Check-the-assembler_code.sh.gz]]


    The script can be used with one of the commands:
    We prefer no space at the beginning of the directive. Some (not many) files need to be corrected to unify to all the other files.
    * save
    * test
    * clean


    == Don't test a subdirectory ==
    {{Output|1=// some files use this
    # include <A/b>


    If a '''.no_coding_file''' file is present on a subdirectory, the test will not be done.
    // we prefer to unify the coding style
    #include <A/b>}}


    == The scripts ==
    *Space-Include-check.sh
    *SpaceInclude.awk


    The first script is '''to check''' a single file or a complete directory for all .h and
    === Place '''*''' and '''&''' next to the variable ===
    .cpp files.


    If present, the second script '''makes the changes''' for a single file or a complete
    The declaration S *D; declares D as a pointer to the type determined by decl-specifier-seq S.
    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.
    For most compilers, the three declarations below are semantically the same:


    ==== don't use any <TAB>s ====
    {{Output|1=int *a;
    *coding-style-check-Tabs.sh
    int* b;
    *The changes are well done with astyle
    int * c
    }}


    Download the scripts: [[Media:Tabs.tar.gz]]
    We prefer the first one, without a space beetwen the star and the name of the variable:


    The output of the '''check''' script is:
    {{Output|1=int *a;
    {{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''').


    ==== Trim the lines ====
    The same rule may be use for:


    *coding-style-check-Trim.sh
    {{Output|1=myFunction(int &a, int& b, int & c)
    *The changes are well done with astyle
    {
        // some lines
    }
    }}


    Download the scripts: [[Media:Trim.tar.gz]]
    We prefer:
    {{Output|1=myFunction(int &a, int &b, int &c)
    }}


    The output of the '''check''' script is:
    The awk-script checks also the occurences of:
    {{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:
    * '''( )''' and '''( )''' ''empty function call''
    * the name of the file which is under test.
    * the number of occurence, the line number, the position found and the line itself.


    ==== Only single empty lines should be used ====
    * '''enum {''' ''untyped enum''
    Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Whitespace


    *coding-style-check-Twice.sh
    Not all the ouputs are real errors. Some codings might be correct.
    *coding-style-change-Twice.sh
    * astyle cannot (yet) do it


    Download the scripts: [[Media:Twice.tar.gz]]
    *NoSpace-check.sh
    *NoSpace.awk
    *using astyle to make the changes:
    {{Output| 1=astyle --reference=name --align-pointer=name
    }}


    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:
    Some lines with must be manually corrected.
    *removes all the next empty line(s).


    ==== First line, last line(s) may not be empty ====
    === Use '''namespace foo {''' in the same line ===


    Some of the sources have a first empty lines, some have one or more empty last line(s).
    We prefer having all in one line:
    *coding-style-check-First-Last.sh
    {{Output|1=namespace foo {
    *coding-style-change-First-Last.sh
      ...
    *astyle cannot (yet) do it
    }
    }}


    Download the scripts: [[Media:First.tar.gz]]
    *Namespace-check.sh
    *Namespace.awk
    *astyle to make the changes.


    The output of the '''check''' script is:
    === Use '''struct foo''' with '''{''' at the next line ===
    {{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).


    ====put the comments away====
    We prefer having the same coding style for a '''class''' and a '''struct'''
    {{Output|1=struct foo
    {
      ...
    }
    }}


    The comments might contain some keyword. It is very difficult to avoid the confusion with the very simple awk-scripts. We prefer to change all the comments with the same number of empty lines.
    *Struct-check.sh
    *Struct-change.sh
    *Struct.awk


    *Comments.awk
    NOTE: The script must be use after astyle.


    Download the scripts: [[Media:Comments.tar.gz]]
    === Each member initialization of a method in separate line ===


    ====change the strings====
    This example shows the indentation we prefer. Notice that colon sign and comma(s)
    are at the beginning of each initialization line(s):


    It is very difficult to parse the strings correctly, so we prefer to change them to an empty string.
    {{Output|1=class myClass
    {
        // some lines
    public:
        myClass(int r, int b, int i, int j)
            : r(0)
            , b(i)
            , i(5)
            , j(13)
    {
        // more lines
    }
    };
    }}


    *Strings.awk
    *Default-check.sh
    *Default-change.sh
    *Default.awk


    Download the scripts: [[Media:Strings.tar.gz]]
    === Surround all operators with spaces ===


    This is well done with astyle:
    {{Output| 1=astyle --pad-oper
    }}


    After the use of the last two awk-scripts (Comments.awk and Strings.awk), we go on with the next check.
    === '''switch''' rules ===


    ====no "one line" if-statement====
    This example shows the indentation we prefer:


    Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Braces
    {{Output|1=switch (a) {
    case ''one'':
        // some lines
        break;
    case ''two'': {
        // some lines
        break;
    }
    case ''three'': {
        // some lines
        return;
    }
    default:
        // some lines
        break;
    }
    }}


    The following code:
    *Switch-check.sh
    {{Output|1=if ( a > b ) c = 123;}}
    *Switch.awk
    is correct, but we prefer the block:
    *astyle makes the changes
    {{Output|1=if ( a > b ) {
      c = 123;
    } }}
    which is easier to read, to modify.


    It is also possible to put a breakpoint at the line in the block.
    NOTE: By using a new block, we prefer having '''break;''' and '''return;''' within the new block.


    As the awk-script is too simple to recognize all the if-statements, we get some false alarm and
    === '''try-catch''' rules ===
    we can't make the changes automatically.


    *coding-style-check-One-Line-If.sh
    This example shows the indentation we prefer:


    Download the scripts: [[Media:One-Line-If.tar.gz]]
    {{Output|1=try {
        // some lines
    } catch (...) {
    }
    }}


    The output of the '''check''' script is:
    *TryCatch-check.sh
    {{Output|1=check the file /home/guy-kde/Software/coding-style-check/if-example.cpp
    *TryCatch.awk
    1->25: one-line-if found}}


    ====Pedantic====
    === '''if''', '''else''', '''for''', '''while''' (and similar macros) rules ===


    Looking over the git-history, one can find some "pedantic" changes.
    Even for blocks with only one statement, we prefer to use braces such as:
    These are changes to make a better code. The most of them are at the use of macro, where it is not necessary to have a ''';''' at the end ofthe command.
    The script make a check over all these:
    '''AKTEST_MAIN;MAKE_CMD_ROW;Q_DECLARE_FLAGS;Q_PRIVATE_SLOT;Q_DECLARE_METATYPE;Q_DECLARE_OPERATORS_FOR_FLAGS;Q_DE
    CLARE_PRIVATE;Q_DECLARE_PUBLIC;Q_DISABLE_COPY;K_GLOBAL_STATIC;Q_IMPORT_PLUGIN;Q_PROPERTY;Q_UNUSED;QTEST_KDEMAIN;QTEST_MAIN'''


    *coding-style-check-Pedantic.sh
    {{Output|1=if (''condition'') {
    *astyle cannot (yet) do it
        ''statement;''
    }
    }}


    Download the scripts: [[Media:Pedantic.tar.gz]]
    This should be used with the keywords '''if''', '''else''', '''for''', '''while''' and similar macros.


    ====Public====
    *If-check.sh
    *Else-check.sh
    *For-check.sh
    *While-check.sh
    *If.awk
    *Else.awk
    *For.awk
    *While.awk
    *astyle makes the changes.


    We prefer having a space before the keyword public at the definition of a new class:
    {{Output|1=class DbException : public Akonadi::Exception
    {
      ...
    };}}


    *coding-style-check-Public.sh
    But we get some false alarm with statements that extend over more than one line:
    *coding-style-change-Public.sh
    *astyle cannot (yet) do it


    Download the scripts: [[Media:Public.tar.gz]]
    {{Output|1=if (''condition_1''
        && ''condition_2'') {
        ''statement;''
    }
    }}


    ====#include directive====
    === '''typedef struct''' statement over more lines ===


    Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Qt_Includes
    This example shows the indentation we prefer:


    We prefer no space at the beginning of the directive. Some (not many) files need to be corrected to unify to all the other files.
    {{Output|1=typedef struct foo {
        // some lines
    }
    }}


    {{Output|1=// some files use this
    *TypedefStruct-check.sh
    # include <A/b>
    *TypeStruct.awk


    // we prefer, to unify the coding style
    === Don't use '''&''' without a variable ===
    #include <A/b>}}


    *coding-style-check-Space-Include.sh
    It is more readable to have the name of (all) the variable(s) in the first line of a method.


    Download the scripts: [[Media:Space-Include.tar.gz]]
    The chnages must be done manually.


    ====enum without any type====
    === Don't use untyped '''enum''' ===


    Instead of having an untyped enum such as:
    Instead of having an untyped enum such as:
    Line 308: Line 396:
    }}
    }}


    Download the scripts: [[Media:Enum.tar.gz]]
    === Don't use '''enum''' with empty member ===
     
    ====enum without empty element====


    The most compilers do not complain such a code:
    The most compilers do not complain such a code:
    Line 320: Line 406:
    }}
    }}


    The last element is empty.  
    The last element is empty.
    We prefer a "pedantic" code such as:
    We prefer a "pedantic" code such as:


    Line 329: Line 415:
    }}
    }}


    *coding-style-check-Enum-Pedantic.sh
    *EnumPedantic-check.sh
    *EnumPedantic.awk
     
    === No ''';''' after some macros ===
     
    Looking over the git-history, one can find some "pedantic" changes.
    These are changes to make a better code. The most of them are at the use of macro, where it is not necessary to have a ''';''' at the end ofthe command.
    The script make a check over all these:
    '''AKTEST_MAIN;MAKE_CMD_ROW;Q_DECLARE_FLAGS;Q_PRIVATE_SLOT;Q_DECLARE_METATYPE;Q_DECLARE_OPERATORS_FOR_FLAGS;Q_DE
    CLARE_PRIVATE;Q_DECLARE_PUBLIC;Q_DISABLE_COPY;K_GLOBAL_STATIC;Q_IMPORT_PLUGIN;Q_PROPERTY;QTEST_KDEMAIN;QTEST_MAIN'''
     
    *Pedantic-check.sh
    *Pedantic.awk


    The output of the '''check''' script is:
    === No "one line" '''if''', '''else''', '''for''' or '''while''' statement ===
    {{Output|1=check the file /home/guy-kde/Software/coding-style-check/enum-example.cpp
     
    enum with ,} found at
    Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Braces
    3->    bElement,
     
    4->  }
    The following code:
    {{Output|1=if (a > b) c = 123;}}
    is correct, but we prefer the block:
    {{Output|1=if (a > b) {
       c = 123;
    }
    }}
    }}
    which is easier to debug, to read and to modify.


    Download the scripts: [[Media:Enum-Pedantic.tar.gz]]
    It is also possible to put a breakpoint at the line in the block.


    ==== Some more space(s)  ====
    As the awk-script is too simple to recognize all the if-statements, we get some false alarm and
    we can't make the changes automatically.


    The declaration S *D; declares D as a pointer to the type determined by decl-specifier-seq S.
    *OneLine-If.sh
    *OneLine-Else.sh
    *If.awk
    *Else.awk


    The most compilers do not make any difference for such lines of code:
    === No space between some keywords ===


    {{Output|1=int *a;
    We don't want to have a space:
    int* b;
    *between '''&''' and '''>'''
    int * c}}
    *between '''*''' and '''>'''
    *between '''(''' and ''')''', an empty parameter list.


    We prefer the first one, without a space beetwen the star and the name of the variable:
    *NoSpace-check.sh
    *NoSpace.awk


    {{Output|1=int *a;}}
    === No space around the index of an array ===


    The same rule may be use for:
    We don't want to have spaces around the index of an array element.


    {{Output|1=myFunction( int &a, int& b, int & c)
    *SpaceInArray-check.sh
    {
    *SpaceInArray-change.sh
        // some lines
    *SpaceInArray.awk
    }
    }}


    We prefer:
    === No space around an expression surrounded with braces ===
    {{Output|1=myFunction( int &a, int &b, int &c) }}


    The awk-script checks also the occurences of:
    We prefer function definition and function call with no space after the opening brace and before the closing brace.
    * '''&,'''
    * '''& >'''
    * '''* >'''
    * '''( )''' and '''(  )''' ''empty function call''
    * '''[ ''' and ''' ]''' ''index of an array''
    * '''enum {''' ''untyped enum''


    Not all the ouputs are real errors. Some codings might be correct.
    *Parenthesis-check.sh
    *Parenthesis.awk
    *This is well done with astyle:
    {{Output| 1=astyle --unpad-paren
    }}


    *coding-style-check-NO-Space.sh
    *astyle --reference=name
    Note that astyle makes also changes within the macros SIGNAL and SLOT, which aren't desired.
    Note that astyle makes also changes within the macros SIGNAL and SLOT, which aren't desired.
    This can be corrected with a Qt-utility:
    This can be corrected with a Qt-utility qt5/qtrepotools/util/normalize/normalize:
    normalize ''filename''
    {{Output| 1=normalize --modify ''filename''
    }}
     
    === No space before ''':''' in a case statement ===


    Some lines with "type & name..." must be manually corrected.
    We don't provide (yet) any check for this rule.


    Download the scripts: [[Media:NO-Space.tar.gz]]
    === No space before ''';''' at the end of statement ===


    The script gives informations about the found line(s).
    We don't provide (yet) any check for this rule.


    ==== Member initialization in a class  ====
    === No ''');''' alone in a line ===


    This example shows the indentation we prefer:
    This is sometime to be find with a function call with many arguments, listed on many lines.
    *ParenthesisAlone-check.sh
    *ParenthesisAlone.awk


    {{Output|1=class myClass {
    === No space before a comma ===
        // some lines
    public:
        myClass( int i )
            : r( a )
            , b( i )
            , i( i )
            , j( this->i )
    {
        // more lines
    }
    }}


    *coding-style-check-Default.sh
    This is sometime to be found in a function call.
    *astyle cannot (yet) do it


    Download the scripts: [[Media:Default.tar.gz]]
    *SpaceComma-check.sh
    *SpaceComma.awk


    But the script produces a false alarm with the code:
    === Operator overloading ===
    {{Output| 1=if ( ''<expression>'' ) ? a : b;
    }}


    The changes must be done manualy
    As written at:


    ==== Parenthesis ====
    http://www.drbio.cornell.edu/pl47/programming/TICPP-2nd-ed-Vol-one-html/Chapter12.html


    We prefer function definition and function call with no space after the opening brace and before the closing brace.
    "... Defining an overloaded operator is like defining a function, but the name of that function is operator@, in which @ represents the operator that’s being overloaded. ..."


    *coding-style-check-Parenthesis.sh
    Some sources use a space after the reserved word operator. We prefer to use the syntax without space.
    *astyle


    Download the scripts: [[Media:Parenthesis.tar.gz]]
    *Operator-check.sh
    *Operator-change.sh
    *Operator.awk


    ==== Switch statement ====
    == Use all the scripts ==


    This example shows the indentation we prefer:
    All the scripts can be used with one only script.


    {{Output|1=switch ( a ) {
    == Check the objects and the libs ==
    case ''one'':
        // some lines
        break;
    case ''two'':
        // some lines
        break;
    default:
        // some lines
        break;
    }
    }}


    *coding-style-check-Switch.sh
    Since the changes described above are only coding style changes, they are ignored by the compiler.
    *astyle
    Therefore, the result of the compilation is expected to be exactly the same after applying any of the rules.


    Download the scripts: [[Media:Switch.tar.gz]]
    To check this, one uses the '''Md5sum-the-Objects.sh'''.
    Same for the libs. Use the '''Md5sum-the-Libs.sh'''.


    ==== Use block  braces ====
    The script can be used with one of the commands:
    * save
    * test
    * clean


    Even for block with only one statement, we prefer to use braces such as:
    '''An example:'''


    {{Output|1=if (''condition'') {
    {{Input|1=cd <some_kdepim_directory>
        ''statement;''
    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>
    ...}}


    This should be used with the keywords '''if''', '''for''', '''while''' and '''FOREACH'''.
    {{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}}


    The output of the '''check''' script is:
    Now, one makes somes change(s) on the source(s) and:


    {{Output|1=check the file /home/guy-kde/projects/test-if.cpp
    {{Input| 1=make}}
    1->62: if without { at end of line:    if ( collection.cachePolicyLocalParts() )
    }}


    *coding-style-check-If.sh
    Depending on the Makefile, some objects will be compiled again:
    *astyle


    Download the scripts: [[Media:If.tar.gz]]
    {{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>}}


    But we get some false alarm with statement over more than one line:
    {{Input|1=Check-the-Objects.sh test}}


    {{Output|1=if ( ''condition_1''
    The script finds all the new objects, makes a comparision with the saved version:
        && ''condition_2'' ) {
    {{Output|1=test the object ./akonadi/CMakeFiles/akonadi-kde.dir/statisticsproxymodel.cpp.o
        ''statement;''
    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
    }}
    }}


    ==== Use one space after each keyword, but not after a cast ====
    == Check the assembler files ==
    If we add or remove some lines, the debug information included in the object file will change also.


    Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Whitespace
    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 most of the keywords, it is not necessary to make a test. Because  the sources have been already compiled. For example this code never appear in a source:
    For this reason it is no more possible to compare the objects.
    {{Output|1=inta;
    We have to compare the assembler files.
    floatb;}}
    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 information before the comparision can take place.


    Some of the keywords are alone in the statement, such as '''break''' and '''continue'''. No test is necessary.
    === Generate the assembler files ===


    The only tests we have to do are the ones where a keyword is (or can be) followed
    To generate the assembler files, we only need to modify the ''build.make'' in every folder.
    by a sign '''( { [ :'''


    These are:
    The script '''Prepare-build_make_files.sh''' works on the all directory, finds the line with the compiler command,
    '''alignas decltype alignof noexcept typeid asm static_assert switch if catch while for sizeof new Q_FOREACH do try enum union Q_FOREVER bool char char16_t char32_t double float int long wchar_t signed unsigned short'''
    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'''.


    For only '''one''' keyword:
    === Remove the debug information ===
    *coding-style-check-SpaceAfterKeyword.sh
    *coding-style-change-SpaceAfterKeyword.sh


    For '''all''' keywords above:
    The debug information changes with the changes of line numbers.
    *coding-style-check-SpaceAfter.sh
    We drop all the debug information before making the test.
    *coding-style-change-SpaceAfter.sh


    Download the scripts: [[Media:SpaceAfter.tar.gz]]
    The script to check the assembler files can be used in the same way as the one above (Check-the-Objects.sh).
    To check this, one uses the '''Check-the-assembler_code.sh'''.


    The output of the '''check''' script is:
    The script can be used with one of the commands:
    {{Output|1=check the file /home/guy-kde/projects/kdepimlibs/akonadi/contact/contactstreemodel.cpp
    * save
    1->98:  if( at 10:          if( contact.realName().isEmpty() ) {
    * test
    2->99:  if( at 12:            if( contact.preferredEmail().isEmpty() ) {
    * clean
    }}


    The '''change''' script:
    == The results of the migration ==
    *puts a space after the keyword.
     
    ==== Use all the scripts ====
     
    All the scripts can be used with one only script.


    Download the scripts: [[Media:All.tar.gz]]
    The results can be seen [http://techbase.kde.org/ResultsOfTheMigration here].

    Revision as of 17:56, 4 November 2014

    Purpose of this document

    This document describes the recommended coding style for kdepim and akonadi. 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 and akonadi coding style follows the Kdelibs coding style.

    But we have some more rules for some more situations.

    Why is coding Style useful?

    Let us make a comparision with real life. To make an addition, one can write:

    123
    +      456
      ==========
         =      579

    But we have learned in primary school to write:

    Addition
      123
     +456
     ====
     =579

    Which is much more readable, easy to control (or debug).

    This is Coding Style: not mandatory, but very useful and pretty to read.

    What do we need?

    We need at least:

    • a specification (a set of rules) for the coding style of the sources
    • some tools to check the sources against the specification
    • some tools to change the sources


    astyle is a very suitable tool to make such changes. But astyle doesn't implement (yet) all the specification rules.

    You can find below some awk-scripts which help us to check all the rules.

    You can find below some awk-scripts which help us to make most of the changes. The last part must be done manually.

    The specification rules of coding style for kdepim and akonadi

    These are the sub-sections under The rules and the scripts ...

    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, there are one or two script(s).

    The main part of the changes can be done with astyle: http://astyle.sourceforge.net/

    The results can be seen here.

    Download Coding Style

    You can download the software with test files and install instructions.

    Download Coding Style: Media:CodingStyle.tar.gz

    Two scripts to check all the rules and to make the all the changes

    Most of the rules can be checked with the scripts below. For some of the rules, we don't have a script to change the sources. It is better first to make a check for such a rule, second to make the modification(s) manually to suscript the rule(s).

    There are two scripts that run all the checks and apply all the changes at once:

    • All-Check.sh
    • Change-All.sh

    For each specification rule, the name of the scripts to check and apply the changes are given at the beginning of the section.

    The rules and the scripts to check and to make the changes

    The first script is to check a single file or all .h and .cpp files in a directory.

    If present, the second script applies the changes. For some complicated situations, the script makes no change.

    You can use the scripts for your own work. It is recommended to use them in this order.

    Don't test all directories

    If a .no_coding_style file is present on a directory, the test will not be done.

    If a .no_recursion file is present on a directory, we do not explore the subdirectory(ies)

    Indentation with four spaces, don't use any <TAB>s

    • Tabs-check.sh
    • Tabs.awk
    • The changes are well done with
    astyle --indent=spaces=4

    Trim the lines

    • Trim-check.sh
    • Trim.awk
    • The changes are well done with:
    astyle --indent=spaces

    Only single empty lines

    Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Whitespace

    • Twice-check.sh
    • Twice-change.sh
    • Twice.awk

    The first line and the last line(s) may not be empty

    Some of the sources have empty lines at the beginning of the file. Some have one or more empty last line(s).

    • First-check.sh
    • First-change.sh
    • First.awk

    Only one statement per line

    We don't provide (yet) any check for this rule.

    Variable declaration

    We follow the kdelibs rule: [[1]] We don't provide (yet) any check for this rule.

    Only one declaration per line

    We follow the kdelibs rule: [[2]] We don't provide (yet) any check for this rule.

    Use one space after each keyword, but not after a cast

    Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Whitespace

    For most of the keywords, it is not necessary to make a test. Because the sources have been already compiled. For example this code never appear in a compiled source:

    intmyVariableAa;
    floatmyVariableBb;

    In this case, the missing space leads to a syntax error which is detected by the compiler. We don't need to check this manually.

    Some of the keywords are alone in the statement, such as break and continue. No test is necessary.

    The only tests we have to do are the ones where a keyword is (or can be) followed by a sign ( { [ :

    These are: alignas decltype alignof noexcept typeid asm static_assert switch if catch while for foreach sizeof new Q_FOREACH FOREACH do try enum union Q_FOREVER bool char char16_t char32_t double float int long wchar_t signed unsigned short

    • SpaceAfter-check.sh
    • SpaceAfter-change.sh
    • SpaceAfter.awk

    Use a space after the name of the class

    We prefer having a space before the keyword public at the definition of a new class:

    class DbException : public Akonadi::Exception
    {
      ...
    };
    • Public-check.sh
    • Public-change.sh
    • Public.awk

    #include directive

    Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Qt_Includes

    We prefer no space at the beginning of the directive. Some (not many) files need to be corrected to unify to all the other files.

    // some files use this
    # include <A/b>
    
    // we prefer to unify the coding style
    #include <A/b>
    • Space-Include-check.sh
    • SpaceInclude.awk

    Place * and & next to the variable

    The declaration S *D; declares D as a pointer to the type determined by decl-specifier-seq S.

    For most compilers, the three declarations below are semantically the same:

    int *a;
    int* b;
    int * c

    We prefer the first one, without a space beetwen the star and the name of the variable:

    int *a;

    The same rule may be use for:

    myFunction(int &a, int& b, int & c)
    {
        // some lines
    }

    We prefer:

    myFunction(int &a, int &b, int &c)

    The awk-script checks also the occurences of:

    • &,
    • & >
    • * >
    • ( ) and ( ) empty function call
    • enum { untyped enum

    Not all the ouputs are real errors. Some codings might be correct.

    • NoSpace-check.sh
    • NoSpace.awk
    • using astyle to make the changes:
    astyle --reference=name --align-pointer=name


    Some lines with must be manually corrected.

    Use namespace foo { in the same line

    We prefer having all in one line:

    namespace foo {
      ...
    }
    • Namespace-check.sh
    • Namespace.awk
    • astyle to make the changes.

    Use struct foo with { at the next line

    We prefer having the same coding style for a class and a struct

    struct foo
    {
      ...
    }
    • Struct-check.sh
    • Struct-change.sh
    • Struct.awk

    NOTE: The script must be use after astyle.

    Each member initialization of a method in separate line

    This example shows the indentation we prefer. Notice that colon sign and comma(s) are at the beginning of each initialization line(s):

    class myClass
    {
        // some lines
    public:
        myClass(int r, int b, int i, int j)
            : r(0)
            , b(i)
            , i(5)
            , j(13)
    {
        // more lines
    }
    };
    • Default-check.sh
    • Default-change.sh
    • Default.awk

    Surround all operators with spaces

    This is well done with astyle:

    astyle --pad-oper

    switch rules

    This example shows the indentation we prefer:

    switch (a) {
    case one:
        // some lines
        break;
    case two: {
        // some lines
        break;
    }
    case three: {
        // some lines
        return;
    }
    default:
        // some lines
        break;
    }
    • Switch-check.sh
    • Switch.awk
    • astyle makes the changes

    NOTE: By using a new block, we prefer having break; and return; within the new block.

    try-catch rules

    This example shows the indentation we prefer:

    try {
        // some lines
    } catch (...) {
    }
    • TryCatch-check.sh
    • TryCatch.awk

    if, else, for, while (and similar macros) rules

    Even for blocks with only one statement, we prefer to use braces such as:

    if (condition) {
        statement;
    }

    This should be used with the keywords if, else, for, while and similar macros.

    • If-check.sh
    • Else-check.sh
    • For-check.sh
    • While-check.sh
    • If.awk
    • Else.awk
    • For.awk
    • While.awk
    • astyle makes the changes.


    But we get some false alarm with statements that extend over more than one line:

    if (condition_1
        && condition_2) {
        statement;
    }

    typedef struct statement over more lines

    This example shows the indentation we prefer:

    typedef struct foo {
        // some lines
    }
    • TypedefStruct-check.sh
    • TypeStruct.awk

    Don't use & without a variable

    It is more readable to have the name of (all) the variable(s) in the first line of a method.

    The chnages must be done manually.

    Don't use untyped enum

    Instead of having an untyped enum such as:

    enum {
        aElement= 123
    }

    we prefer a #define directive:

    #define aElement 123

    Don't use enum with empty member

    The most compilers do not complain such a code:

    enum mytype {
        aElement,
        bElement,
    }

    The last element is empty. We prefer a "pedantic" code such as:

    enum mytype {
        aElement,
        bElement
    }
    • EnumPedantic-check.sh
    • EnumPedantic.awk

    No ; after some macros

    Looking over the git-history, one can find some "pedantic" changes. These are changes to make a better code. The most of them are at the use of macro, where it is not necessary to have a ; at the end ofthe command. The script make a check over all these: AKTEST_MAIN;MAKE_CMD_ROW;Q_DECLARE_FLAGS;Q_PRIVATE_SLOT;Q_DECLARE_METATYPE;Q_DECLARE_OPERATORS_FOR_FLAGS;Q_DE CLARE_PRIVATE;Q_DECLARE_PUBLIC;Q_DISABLE_COPY;K_GLOBAL_STATIC;Q_IMPORT_PLUGIN;Q_PROPERTY;QTEST_KDEMAIN;QTEST_MAIN

    • Pedantic-check.sh
    • Pedantic.awk

    No "one line" if, else, for or while statement

    Refer to http://techbase.kde.org/Policies/Kdelibs_Coding_Style#Braces

    The following code:

    if (a > b) c = 123;

    is correct, but we prefer the block:

    if (a > b) {
       c = 123;
    }

    which is easier to debug, to read and to modify.

    It is also possible to put a breakpoint at the line in the block.

    As the awk-script is too simple to recognize all the if-statements, we get some false alarm and we can't make the changes automatically.

    • OneLine-If.sh
    • OneLine-Else.sh
    • If.awk
    • Else.awk

    No space between some keywords

    We don't want to have a space:

    • between & and >
    • between * and >
    • between ( and ), an empty parameter list.
    • NoSpace-check.sh
    • NoSpace.awk

    No space around the index of an array

    We don't want to have spaces around the index of an array element.

    • SpaceInArray-check.sh
    • SpaceInArray-change.sh
    • SpaceInArray.awk

    No space around an expression surrounded with braces

    We prefer function definition and function call with no space after the opening brace and before the closing brace.

    • Parenthesis-check.sh
    • Parenthesis.awk
    • This is well done with astyle:
    astyle --unpad-paren

    Note that astyle makes also changes within the macros SIGNAL and SLOT, which aren't desired. This can be corrected with a Qt-utility qt5/qtrepotools/util/normalize/normalize:

    normalize --modify filename

    No space before : in a case statement

    We don't provide (yet) any check for this rule.

    No space before ; at the end of statement

    We don't provide (yet) any check for this rule.

    No ); alone in a line

    This is sometime to be find with a function call with many arguments, listed on many lines.

    • ParenthesisAlone-check.sh
    • ParenthesisAlone.awk

    No space before a comma

    This is sometime to be found in a function call.

    • SpaceComma-check.sh
    • SpaceComma.awk

    Operator overloading

    As written at:

    http://www.drbio.cornell.edu/pl47/programming/TICPP-2nd-ed-Vol-one-html/Chapter12.html

    "... Defining an overloaded operator is like defining a function, but the name of that function is operator@, in which @ represents the operator that’s being overloaded. ..."

    Some sources use a space after the reserved word operator. We prefer to use the syntax without space.

    • Operator-check.sh
    • Operator-change.sh
    • Operator.awk

    Use all the scripts

    All the scripts can be used with one only script.

    Check the objects and the libs

    Since the changes described above are only coding style changes, they are ignored by the compiler. Therefore, the result of the compilation is expected to be exactly the same after applying any of the rules.

    To check this, one uses the Md5sum-the-Objects.sh. Same for the libs. Use the Md5sum-the-Libs.sh.

    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:

    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 information included in the object file will 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 information before the comparision can 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 information

    The debug information changes with the changes of line numbers. We drop all the debug information before making the test.

    The script to check the assembler files can be used in the same way as the one above (Check-the-Objects.sh). To check this, one uses the Check-the-assembler_code.sh.

    The script can be used with one of the commands:

    • save
    • test
    • clean

    The results of the migration

    The results can be seen here.