Changes between Version 1 and Version 2 of Documentation/T3Q/Quality-Checks/Code-Style


Ignore:
Timestamp:
02/21/12 11:52:07 (13 years ago)
Author:
phdmakk
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • Documentation/T3Q/Quality-Checks/Code-Style

    v1 v2  
    1  
    21=== Code Style === 
    3  
    42==== There Must Be No Labels or Goto Statements ==== 
    5  - '''Symbolic Name in XML Configuration''': checkNoLabelsOrGotoStatements 
    6  - '''Dependant Tags in XML Configuration''': - 
     3 * '''Symbolic Name in XML Configuration''': checkNoLabelsOrGotoStatements 
     4 * '''Dependant Tags in XML Configuration''': - 
    75 
    86The check makes sure that there are no labels and goto statements in the test code. 
    97 
    108==== There Must Be No Nested Alt Statements ==== 
    11  - '''Symbolic Name in XML Configuration''': checkNoNestedAltStatements 
    12  - '''Dependant Tags in XML Configuration''': maximumAllowedNestingDepth 
     9 * '''Symbolic Name in XML Configuration''': checkNoNestedAltStatements 
     10 * '''Dependant Tags in XML Configuration''': maximumAllowedNestingDepth 
    1311 
    1412The check makes sure that there are no alt statements nested within other alt statements or altstep definitions beyond a given depth (specified via the '''maximumAllowedNestingDepth''' configuration tag). The topmost alt or the enclosing altstep definition is considered of depth 0, first level nesting is of depth 1, and so on. The default nesting depth is 0, meaning that no alt statements are allowed within other alt statements or altstep definitions. 
    … …  
    2018'''Output''' 
    2119 
    22 The output includes the scope of the alt statement (starting line - end line) and has the following format:  
     20The output includes the scope of the alt statement (starting line - end line) and has the following format: 
    2321 
    24 {{{Alt statement nesting depth (<DEPTH>) exceeds maximum allowed nesting depth (<maximumAllowedNestingDepth>)!}}} 
     22`Alt statement nesting depth (<DEPTH>) exceeds maximum allowed nesting depth (<maximumAllowedNestingDepth>)!` 
    2523 
    2624==== There Must Be No Permutation Keyword ==== 
    27  - '''Symbolic Name in XML Configuration''': checkNoPermutationKeyword 
    28  - '''Dependant Tags in XML Configuration''': - 
     25 * '''Symbolic Name in XML Configuration''': checkNoPermutationKeyword 
     26 * '''Dependant Tags in XML Configuration''': - 
    2927 
    3028The check makes sure that there are no permutation keywords in the test code. 
    3129 
    3230==== There Must Be No !AnyType Keyword ==== 
    33  - '''Symbolic Name in XML Configuration''': checkNoAnyTypeKeyword 
    34  - '''Dependant Tags in XML Configuration''': - 
     31 * '''Symbolic Name in XML Configuration''': checkNoAnyTypeKeyword 
     32 * '''Dependant Tags in XML Configuration''': - 
    3533 
    3634The check makes sure that there are no anytype keywords in the test code. 
    3735 
    3836==== There Must Be No Modified Template of a Modified Template ==== 
    39  - '''Symbolic Name in XML Configuration''': checkNoModifiedTemplateOfModifiedTemplate 
    40  - '''Dependant Tags in XML Configuration''': - 
     37 * '''Symbolic Name in XML Configuration''': checkNoModifiedTemplateOfModifiedTemplate 
     38 * '''Dependant Tags in XML Configuration''': - 
    4139 
    4240The check makes sure that there are no modified templates are derived from modified templates. In the example, myTemplate3 is a modified template of degree 2 and myTemplate4 is a modified template of degree 4. Both will be reported by T3Q. 
    … …  
    4745 
    4846==== Local Definitions Must Be Declared at the Beginning of Testcases, Functions, Altsteps, and Component Definitions, in a Specified Order ==== 
    49  - '''Symbolic Name in XML Configuration''': checkLocalDefinitionsComeFirst 
    50  - '''Dependant Tags in XML Configuration''': localDefinitionTypes 
     47 * '''Symbolic Name in XML Configuration''': checkLocalDefinitionsComeFirst 
     48 * '''Dependant Tags in XML Configuration''': localDefinitionTypes 
    5149 
    5250This is an evolved version of the check for variables only in the same context (declared before any other statements). In this version, not only variables, but also local constants and timers can be considered (if configured). Additionally, the order of occurrence of these three classes of local definitions can be specified and checked for. With the help of the help of the '''localDefinitionTypes''' configuration tag, which contains a list '''string''' tags, the contents and the order of local definitions can be specified. The default configuration contains four possible types of local definitions: '''!VarInstance''' (variables), '''!ConstDef''' (local constants), '''!TimerInstance''' (local timers), and '''!PortInstance''' (port instances, only within components), configured in this order, meaning that constants are expected to be declared after all variables and before all timers (and ports, in the context of component definitions): 
     51 
    5352{{{ 
    5453      <localDefinitionTypes> 
    … …  
    5958      </localDefinitionTypes> 
    6059}}} 
    61  
    62  
    6360This order can be changed by moving the configured entries up and down the list. If timers and ports are to be disregarded, for example, then the whole configuration tags shall be omitted, so that the configuration will be: 
    6461 
    … …  
    6966      </localDefinitionTypes> 
    7067}}} 
    71  
    7268Only the local definition types provided in the default configuration can be used, and only if spelled correctly, meaning that case-sensitivity matters in this context ("constdef" hence will not be recognized). 
    7369 
    … …  
    7571 
    7672==== Import Statements Must Be Declared at the Beginning of Modules ==== 
    77  - '''Symbolic Name in XML Configuration''': checkImportsComeFirst 
    78  - '''Dependant Tags in XML Configuration''': - 
     73 * '''Symbolic Name in XML Configuration''': checkImportsComeFirst 
     74 * '''Dependant Tags in XML Configuration''': - 
    7975 
    8076Similarly to "Variables Must Be Declared at the Beginning of Testcases, Functions and Altsteps", this check makes sure that all import statements are always at the beginning of any module. 
    8177 
    8278==== There Must Be No Duplicated Identifiers On the Module Level ==== 
    83  - '''Symbolic Name in XML Configuration''': checkNoDuplicatedModuleDefinitionIdentifiers 
    84  - '''Dependant Tags in XML Configuration''': - 
     79 * '''Symbolic Name in XML Configuration''': checkNoDuplicatedModuleDefinitionIdentifiers 
     80 * '''Dependant Tags in XML Configuration''': - 
    8581 
    8682This check will make sure there are no identical identifiers for definitions on the module level among the analyzed modules (regardless of type). 
    8783 
     84==== There Must Be No Unused Definitions On the Module Level ==== 
     85 * '''Symbolic Name in XML Configuration''': checkZeroReferencedModuleDefinitions 
     86 * '''Dependant Tags in XML Configuration''': zeroReferencedModuleDefinitionsExcludedRegExp 
    8887 
    89 ==== There Must Be No Unused Definitions On the Module Level ==== 
    90  - '''Symbolic Name in XML Configuration''': checkZeroReferencedModuleDefinitions 
    91  - '''Dependant Tags in XML Configuration''': zeroReferencedModuleDefinitionsExcludedRegExp 
    92  
    93 This check will make sure there are no unused definitions on the module level among the analyzed modules, including references through imports. References within import statements however will be disregarded, meaning that if a definition is imported, but never used, it will be considered an unused definition as well. Group definitions are excluded from this check. Additionally, through the '''zeroReferencedModuleDefinitionsExcludedRegExp''' configuration tag, a regular expression can be specified to allow certain modules (based on the module name) to be excluded from this check. The regular expression is empty by default, meaning that all modules are considered by default.  
     88This check will make sure there are no unused definitions on the module level among the analyzed modules, including references through imports. References within import statements however will be disregarded, meaning that if a definition is imported, but never used, it will be considered an unused definition as well. Group definitions are excluded from this check. Additionally, through the '''zeroReferencedModuleDefinitionsExcludedRegExp''' configuration tag, a regular expression can be specified to allow certain modules (based on the module name) to be excluded from this check. The regular expression is empty by default, meaning that all modules are considered by default. 
    9489 
    9590==== There Must Be No Inline Templates ==== 
    96  - '''Symbolic Name in XML Configuration''': checkNoInlineTemplates 
    97  - '''Dependant Tags in XML Configuration''': - 
     91 * '''Symbolic Name in XML Configuration''': checkNoInlineTemplates 
     92 * '''Dependant Tags in XML Configuration''': - 
    9893 
    9994This check will make sure there are no inline templates used in the analyzed modules. 
    10095 
    10196==== There Must Be No Over-specific Runs On Clauses ==== 
    102  - '''Symbolic Name in XML Configuration''': checkNoOverSpecificRunsOnClauses 
    103  - '''Dependant Tags in XML Configuration''': recursionInCheckNoOverSpecificRunsOnClauses 
     97 * '''Symbolic Name in XML Configuration''': checkNoOverSpecificRunsOnClauses 
     98 * '''Dependant Tags in XML Configuration''': recursionInCheckNoOverSpecificRunsOnClauses 
    10499 
    105 This check will make sure no over-specific '''runs on''' clauses are used. An over-specific runs on clause is when none of the component element definitions (variables, timers, constants, and ports) of the component used in the runs on clause are referenced within the body of the function, test case, or alststep with the runs on clause. If at least one of the component element definitions is referenced within the body of the function, test case, or altstep, then no problem is reported. If the '''recursionInCheckNoOverSpecificRunsOnClauses''' setting is enabled (which it is by default), also the functions and altsteps referenced within the body of the current construct will be inspected. This is due to the fact that often wrapper functions are used that do not make direct use of the component element definitions themselves. 
     100This check will make sure no over-specific '''runs on''' clauses are used. An over-specific runs on clause is when none of the component element definitions (variables, timers, constants, and ports) of the component used in the runs on clause are referenced within the body of the function or alststep with the runs on clause. If at least one of the component element definitions is referenced within the body of the function or altstep, then no problem is reported. If the '''recursionInCheckNoOverSpecificRunsOnClauses''' setting is enabled (which it is by default), also the functions and altsteps referenced within the body of the current construct will be inspected. This is due to the fact that often wrapper functions are used that do not make direct use of the component element definitions themselves. 
     101 
     102As of v1.0.3, test cases are not considered in this check, due to a  change request based on the notion that test cases are required to have a  runs on clause, regardless of whether they actually utilize any of the  component element definitions of the MTC. 
    106103 
    107104'''Example:''' 
    … …  
    110107 
    111108==== There Must Be No Unused Imports ==== 
    112  - '''Symbolic Name in XML Configuration''': checkNoUnusedImports 
    113  - '''Dependant Tags in XML Configuration''': - 
     109 * '''Symbolic Name in XML Configuration''': checkNoUnusedImports 
     110 * '''Dependant Tags in XML Configuration''': - 
    114111 
    115112This is a rather complex quality check, that seeks to identify unused imports. As a first step it checks whether the imported module exists. If it does not exist, it is either because the imported module is not a part of the analyzed input, or because the name of the imported module has been misspelled. Whatever the case, if the module cannot be resolved, a corresponding message is provided and the check for that particular import statement is finished. If the module can be resolved, depending on the context, the following situations are checked: 
    116113 
    117  1. If an '''all''' keyword is used in a non-type-restrictive manner (i.e. not associated to a certain definition type), then it is checked whether there is at least one reference of any module definition from the imported module within the importing module. Whether there are exceptions specified in the import statement makes no difference in this case, because in such a scenario, it is no longer possible to have references pointing back to the imported definition and thus the results of this check remain correct.  
     114 1. If an '''all''' keyword is used in a non-type-restrictive manner (i.e. not associated to a certain definition type), then it is checked whether there is at least one reference of any module definition from the imported module within the importing module. Whether there are exceptions specified in the import statement makes no difference in this case, because in such a scenario, it is no longer possible to have references pointing back to the imported definition and thus the results of this check remain correct. 
    118115 1. If a non-specific type import is used (i.e. an '''all''' keyword is preceded by definition type keyword), then it is checked whether there is at least one reference of any module definition of the given type from the imported module within the importing module. Same conditions apply as in the non-type-restrictive use of the '''all''' keyword. If all groups are to be considered, then only the definitions within groups are considered, those outside groups are not considered. 
    119  1. If a specific type import is used (i.e. a definition type keyword, followed by a (list of) identifiers), several checks are performed:  
    120   1. Check if the identifier is resolvable. If it is not it means that either the definition is not present within the imported module or the identifier is perhaps misspelled. 
    121   1. If the identifier is resolvable, it is checked whether the definition is actually within the imported module. It may be the case that the definition has already been imported from another module (see also [[wiki:Documentation/T3Q/Quality-Checks/Code-Style#ThereMustBeNoDuplicatedIdentifiersOntheModuleLevel No Duplicated Identifiers]]), in which case a corresponding message is provided and the actual references for that identifier are not checked any further. It may also be the case that the definition has already been imported from another module, but also does not exist in the module from which it is attempted to be imported again (the definition has been moved perhaps?!), in which case another corresponding message is provided, and no further analysis of the actual references is performed. 
    122   1. Finally, if the identifier is uniquely and correctly resolvable, is is checked whether there are any references to that imported definition within the importing module. If a specific group is imported, it is checked whether any of the definitions within that group are referenced in the importing module instead. 
     116 1. If a specific type import is used (i.e. a definition type keyword, followed by a (list of) identifiers), several checks are performed: 
     117   1. Check if the identifier is resolvable. If it is not it means that either the definition is not present within the imported module or the identifier is perhaps misspelled. 
     118   1. If the identifier is resolvable, it is checked whether the definition is actually within the imported module. It may be the case that the definition has already been imported from another module (see also [[wiki:Documentation/T3Q/Quality-Checks/Code-Style#ThereMustBeNoDuplicatedIdentifiersOntheModuleLevel No Duplicated Identifiers]]), in which case a corresponding message is provided and the actual references for that identifier are not checked any further. It may also be the case that the definition has already been imported from another module, but also does not exist in the module from which it is attempted to be imported again (the definition has been moved perhaps?!), in which case another corresponding message is provided, and no further analysis of the actual references is performed. 
     119   1. Finally, if the identifier is uniquely and correctly resolvable, is is checked whether there are any references to that imported definition within the importing module. If a specific group is imported, it is checked whether any of the definitions within that group are referenced in the importing module instead. 
    123120 
    124121Note that currently this check is rather computationally expensive and thus '''disabled by default'''. Once suitable optimizations are added, it will be re-enabled by default. 
    125122 
    126123==== There Must Be No Unused Formal Parameters ==== 
    127  - '''Symbolic Name in XML Configuration''': checkNoUnusedFormalParameters 
    128  - '''Dependant Tags in XML Configuration''': - 
     124 * '''Symbolic Name in XML Configuration''': checkNoUnusedFormalParameters 
     125 * '''Dependant Tags in XML Configuration''': - 
    129126 
    130127This check makes sure there are no unused formal parameters. There are several peculiarities associated with this quality check: 
     128 
    131129 * External functions are excluded from this check since their formal parameters can never be used within their TTCN-3 definitions 
    132130 * In the case of modified template definitions, all the formal parameters defined in the modified template (currently matched by name only) are not checked again in the modifying template. Only the additional formal parameters defined in the modifying template are checked in such a case. 
    … …  
    135133 
    136134==== There Must Be No Unused Local Definitions ==== 
    137  - '''Symbolic Name in XML Configuration''': checkNoUnusedLocalDefinitions 
    138  - '''Dependant Tags in XML Configuration''': - 
     135 * '''Symbolic Name in XML Configuration''': checkNoUnusedLocalDefinitions 
     136 * '''Dependant Tags in XML Configuration''': - 
    139137 
    140138This check makes sure there are no unused local definitions. This covers local constants, timers, variables, ports, template variables and local template definitions. Currently component definitions, function definitions, altstep definitions and testcase definitions are analyzed, as well as module control parts. 
    141139 
    142140==== There Must Be No Literals ==== 
    143  - '''Symbolic Name in XML Configuration''': checkNoLiterals 
    144  - '''Dependant Tags in XML Configuration''': - 
     141 * '''Symbolic Name in XML Configuration''': checkNoLiterals 
     142 * '''Dependant Tags in XML Configuration''': - 
    145143 
    146144This check makes sure there are no literals used, except in module parameters, template definitions, and constant definitions. Note that while in both module-level constants and local constants literals are permitted, in the case of templates, only template definitions at the module level can contain literals. Note also that currently matching symbols, boolean values, verdicts, omit-values, enumerated values, and address-values are not considered ''literals''. This may be a subject to change. 
    147