mirrors/eiffel-org
1
0
Fork 0
mirror of https://github.com/EiffelSoftware/eiffel-org.git synced 2025-12-07 15:22:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

Created version for 17.01.

Browse Source 
git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@1789 abb3cda0-5349-4a8f-a601-0c33ac3a8c38
This commit is contained in:
eiffel-org
2017-03-10 08:53:03 +00:00
parent 65b7ae1274
commit cb0518b8e1
2887 changed files with 59843 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
documentation/17.01/eiffelstudio/eiffelstudio-reference/metrics-tool/definitions/attributes-metrics-and-measures.wiki Normal file
View File

@@ -0,0 +1,35 @@
[[Property:title|Attributes, metrics and measures]]
[[Property:weight|1]]
[[Property:uuid|4e35583c-25e8-63e7-2c11-ea4d3ed2e2a3]]
The most general notion is "attribute":
{{definition|Attribute|An '''attribute''' is a property, qualitative or quantitative, of software products or processes. }}
<!--break-->
We may distinguish between the product and process cases:
{{definition|Product attribute, process attribute|A '''product attribute''' is an attribute that characterizes a software product or set of products. A '''process attribute''' is an attribute that characterizes a software-related process, such as development, maintenance, documentation, management, or multiple instances of such a process. }}
Examples of attributes include reliability (a product attribute, non-quantitative) and total project cost (process, quantitative).
A metric is simply a quantitative attribute:
{{definition|Metric|A '''metric''' is an attribute whose values are numbers (integers or reals), expressed relative to a certain '''unit''' specified as part of the metric definition. }}
Examples of metrics include the number of source lines of a program (product) and the total cost of a project (process). The metric tool provides by default a set of metrics, they are available in the Metric Evaluation tab of the metric tool
Attributes other than metrics will be called "qualitative":
{{definition|Qualitative attribute|A '''qualitative attribute''' is an attribute other than a metric. }}
An example of qualitative attribute is the reliability of a software product.
The "process" vs. "product" distinction carries over to metrics:
{{definition|Product metric, process metric|A metric is a '''product metric''' if it is a product attribute, a '''process metric''' if it is a process attribute. }}
"Relevance", as defined in the previous section, suggests that the purpose of metrics is to help us gain information about attributes that are of direct interest to us. Often these will be qualitative; for example we may want to estimate the reliability of our software. Metrics provide us with numerical values that can serve to assess or predict such attributes.
Applying a metric will give us measures:
{{definition|Measure|A '''measure''' is the value of a metric for a certain process or product. }}

763
documentation/17.01/eiffelstudio/eiffelstudio-reference/metrics-tool/definitions/criterion-references.wiki Normal file
View File

@@ -0,0 +1,763 @@
[[Property:title|Criterion References]]
[[Property:weight|12]]
[[Property:uuid|52790486-55e8-86dc-67d7-5530d1b342a3]]
==Text Criterion==
'''name_is'''<br/>
'''Syntax:''' name_is "pattern", matching strategy, case-sensitivity<br/>
'''Applicable on:''' Target, Group, Class, Generic, Feature, Assertion, Argument, Local, Line<br/>
'''Remark:''' This criterion will evaluate to True if name of the candidate code element matched the given pattern. For more details about matching strategy and case-sensitivity modifier, see the documentation of text criterion.
'''text_is'''<br/>
'''Syntax:''' text_is "pattern", matching strategy, case-sensitivity<br/>
'''Applicable on:''' Class, Generic, Feature, Assertion, Argument, Local, Line<br/>
'''Remark:''' This criterion will evaluate to True if text of a candidate code element matches the given pattern.
'''top_indexing_contain'''<br/>
'''Syntax:''' top_indexing_contain "pattern", matching strategy, case-sensitivity<br/>
'''Applicable on:''' Class<br/>
'''Remark:''' This criterion will evaluate to True if text (indexing tags are not included) of the top indexing clause in the candidate class matches the given pattern.
'''top_indexing_has_tag'''<br/>
'''Syntax:''' top_indexing_has_tag "pattern", matching strategy, case-sensitivity<br/>
'''Applicable on:''' Class<br/>
'''Remark:''' This criterion will evaluate to True if tags of the top indexing clause in the candidate class matches the given pattern.
'''bottom_indexing_contain'''<br/>
'''Syntax:''' bottom_indexing_contain "pattern", matching strategy, case-sensitivity<br/>
'''Applicable on:''' Class<br/>
'''Remark:'''This criterion will evaluate to True if text (indexing tags are not included) of the bottom indexing clause in the candidate class matches the given pattern.
'''bottom_indexing_has_tag'''<br/>
'''Syntax:''' bottom_indexing_has_tag "pattern", matching strategy, case-sensitivity<br/>
'''Applicable on:''' Class<br/>
'''Remark:'''This criterion will evaluate to True if tags of the bottom indexing clause in the candidate class matches the given pattern.
'''indexing_contain'''<br/>
'''Syntax:''' indexing_contain "pattern", matching strategy, case-sensitivity<br/>
'''Applicable on:'''Class<br/>
'''Remark:'''This criterion will evaluate to True if (top or bottom) indexing clause matches the given pattern.
'''indexing_has_tag'''<br/>
'''Syntax:''' indexing_has_tag "pattern", matching strategy, case-sensitivity<br/>
'''Applicable on:''' Class<br/>
'''Remark:''' This criterion will evaluate to True if tag of (top or bottom) indexing clause of the candidate class matches the given pattern.
==Path Criterion==
'''path_in'''<br/>
'''Syntax:''' path_in "path"<br/>
'''Applicable on:''' Class<br/>
'''Remark:''' This criterion will evaluate to True if path (related to the class's written in group) of the class candidate is "path" or its subdirectory. "path" is in Unix format, i.e., different sections are separated by a "/". On Windows, path matching is case-sensitive, on other platforms, it's case-sensitive.
'''path_is'''<br/>
'''Syntax:''' path_is "path"<br/>
'''Applicable on:''' Class<br/>
'''Remark:''' This criterion will evaluate to True if path (related to the class's written in group) of the class candidate is "path". "path" is in Unix format, i.e., different sections are separated by a "/". On Windows, path matching is case-sensitive, on other platforms, it's case-sensitive.
==Relation Criterion==
'''ancestor_is'''<br/>
'''Syntax:''' ancestor_is {domain}<br/>
'''Applicable on:''' Class, Feature<br/>
'''Remark:''' This criterion will evaluate to True if candidate class (or feature) is descendant of any (if more than one are possible) of the class (or feature) specified in the criterion domain.<br/>
For example, in a class metric,
{{sample|ancestor_is {<eiffel>STRING_8</eiffel>} }}
<br/>
will evaluate to True when a candidate class is a descendant of class <eiffel>STRING_8</eiffel>.<br/>
In a class metric,
{{sample|ancestor_is {<eiffel>LINKED_LIST</eiffel>, <eiffel>DS_LINKED_LIST</eiffel>} }}
will evaluate to True when a candidate class is a descendant of either <eiffel>LINKED_LIST</eiffel> or <eiffel>DS_LINKED_LIST</eiffel>.
'''proper_ancestor_is'''<br/>
'''Syntax:''' proper_ancestor_is {domain}<br/>
'''Applicable on:''' Class<br/>
'''Remark:''' This criterion will evaluate to True if a candidate class is a proper descendant of any of the classes in criterion domain. First, let's use the following figure to demonstrate the concepts of ancestor, proper ancestor, parent and indirect parent. (Note: the hierarchy is not complete) <br/>
[[Image:class-hie|class hierarchy]]
Ancestors of <eiffel>STRING_32</eiffel> are: <eiffel>STRING_32</eiffel>, <eiffel>STRING_GENERAL</eiffel>, <eiffel>INDEXABLE</eiffel>, <eiffel>COMPARABLE</eiffel> and <eiffel>PART_COMPARABLE</eiffel>.<br/>
Proper ancestors of <eiffel>STRING_32</eiffel> are <eiffel>STRING_GENERAL</eiffel>, <eiffel>INDEXABLE</eiffel>, <eiffel>COMPARABLE</eiffel> and <eiffel>PART_COMPARABLE</eiffel>.<br/>
Parents of <eiffel>STRING_32</eiffel> are: <eiffel>STRING_GENERAL</eiffel> and <eiffel>INDEXABLE</eiffel><br/>
Indirect parents of <eiffel>STRING_32</eiffel> are: <eiffel>COMPARABLE</eiffel> and <eiffel>PARTCOMPARABLE</eiffel><br/>
The related concepts of descendants, proper descendants, heirs, indirect heirs follow the same rule but are in the reversed direction. <br/>
'''descendant_is'''<br/>
'''Syntax:''' descendant_is {domain}<br/>
'''Applicable on:''' Class, Feature<br/>
'''Remark:''' This criterion evaluates to True if candidate class is or feature is ancestor of any (if more than one are possible) of the class or feature specified in the criterion domain.<br/>
'''proper_descendant_is'''<br/>
'''Syntax:''' proper_descendant_is {domain}<br/>
'''Applicable on:''' Class<br/>
'''Remark:''' This criterion evaluates to True if a candidate class is a proper ancestor of any of the classes in criterion domain.<br/>
'''parent_is'''<br/>
'''Syntax:''' parent_is {domain}<br/>
'''Applicable on:''' Class<br/>
'''Remark:''' This criterion evaluates to True if a candidate class is a heir of any of the classes in criterion domain.<br/>
'''indirect_parent_is'''<br/>
'''Syntax:''' indirect_parent_is {domain}<br/>
'''Applicable on:''' Class<br/>
'''Remark:''' This criterion evaluates to True if a candidate class is a indirect heir of any of the classes in criterion domain.<br/>
'''heir_is'''<br/>
'''Syntax:''' heir_is {domain}<br/>
'''Applicable on:''' Class<br/>
'''Remark:''' This criterion evaluates to True if a candidate class is a parent of any of the classes in criterion domain.<br/>
'''indirect_heir_is'''<br/>
'''Syntax:''' indirect_heir_is {domain}<br/>
'''Applicable on:''' Class<br/>
'''Remark:''' This criterion evaluates to True if a candidate class is a indirect parent of any of the classes in criterion domain.<br/>
'''client_is'''<br/>
'''Syntax:''' client_is {domain}, directness, normally_referenced, syntactically_referenced<br/>
'''Applicable on:''' Class<br/>
'''Remarks:''' This criterion evaluates to True if a candidate class is supplier of any of the classes in criterion domain. Directness modifier is boolean modifier, if it's True only direct suppliers are picked, if indirect modifier is set, only indirect suppliers are picked. normally_referenced and syntactically_referenced modifiers are both boolean modifiers, they enable to specify how one class is used by another class. Let's use an example to demonstrate these ideas, for example, in class A, there is a feature foo:<br/>
<code>
foo
local
l_str: STRING
l_file: FILE
do
create l_str.make_empty
end
</code>
<br/>
Then both <eiffel>STRING</eiffel> and <eiffel>FILE</eiffel> are suppliers of class <eiffel>A</eiffel>. <eiffel>STRING</eiffel> is normal supplier because a feature make_empty in <eiffel>STRING</eiffel> is invoked in class <eiffel>A</eiffel>, but <eiffel>FILE</eiffel> is a syntactically referenced supplier because no feature from <eiffel>FILE</eiffel> is called from <eiffel>A</eiffel>. Classes explicitly listed in inherit clause of a class are also considered as syntactically referenced suppliers.
Concepts of direct/indirect, normally referenced/syntactically referenced clients follow the same rule except in the other direction.
'''supplier_is'''<br/>
'''Syntax:''' supplier_is {domain}, directness, normally_referenced, syntactically_referenced<br/>
'''Applicable on:''' Class<br/>
'''Remark:'''<br/>
This criterion evaluates to True if a candidate class is client of any of the classes in criterion domain.<br/>
For more information of directness modifier, normally_referenced modifier and syntactically_referenced modifier, see document for relation criterion client_is<br/>
'''callee_is'''<br/>
'''Syntax:''' callee_is {domain}, only_current_version<br/>
'''Applicable on:''' Feature<br/>
'''Remark:'''<br/>
This criterion evaluates to True if a candidate feature is calling any of the feature listed in criterion domain.<br/>
only_current_verision modifier is a boolean modifier, if it's True, when the criterion is evaluated, only the candidate feature is taken into consideration, otherwise, the candidate feature and all its descendant versions are taken into consideration.<br/>
'''caller_is'''<br/>
'''Syntax:''' caller_is {domain}, only_current_version<br/>
'''Applicable on:''' Feature<br/>
'''Remark:'''<br/>
This criterion evaluates to True if a candidate feature is called by any of the feature listed in criterion domain.<br/>
only_current_verision modifier is a boolean modifier, if it's True, when the criterion is evaluated, only the candidate feature is taken into consideration, otherwise, the candidate feature and all its descendant versions are taken into consideration. <br/>
'''assignee_is'''<br/>
'''Syntax:''' assignee_is {domain}, only_current_version<br/>
'''Applicable on:''' Feature<br/>
'''Remark:'''<br/>
This criterion evaluates to True if a candidate feature assigns to any of the feature listed in criterion domain.<br/>
only_current_verision modifier is a boolean modifier, if it's True, when the criterion is evaluated, only the candidate feature is taken into consideration, otherwise, the candidate feature and all its descendant versions are taken into consideration.<br/>
'''assigner_is'''<br/>
'''Syntax:''' assigner_is {domain}, only_current_version<br/>
'''Applicable on:''' Feature<br/>
'''Remark:'''<br/>
This criterion evaluates to True if a candidate feature assigns to any of the feature listed in criterion domain.<br/>
only_current_verision modifier is a boolean modifier, if it's True, when the criterion is evaluated, only the candidate feature is taken into consideration, otherwise, the candidate feature and all its descendant versions are taken into consideration.<br/>
'''createe_is'''<br/>
'''Syntax:''' createe_is {domain}, only_current_version<br/>
'''Applicable on:''' Feature<br/>
'''Remark:'''<br/>
This criterion evaluates to True if a candidate feature creates any of the feature (must be an attribute) listed in criterion domain.<br/>
only_current_verision modifier is a boolean modifier, if it's True, when the criterion is evaluated, only the candidate feature is taken into consideration, otherwise, the candidate feature and all its descendant versions are taken into consideration.<br/>
'''creator_is'''<br/>
'''Syntax:''' creator_is {domain}, only_current_version<br/>
'''Applicable on:''' Feature<br/>
'''Remark:'''<br/>
This criterion evaluates to True if a candidate feature (must be an attribute) is created by any of the feature listed in criterion domain.<br/>
only_current_verision modifier is a boolean modifier, if it's True, when the criterion is evaluated, only the candidate feature is taken into consideration, otherwise, the candidate feature and all its descendant versions are taken into consideration.<br/>
'''is_exported_to'''<br/>
'''Syntax:''' is_exported_to {domain}<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate class is exported to all the classes listed in criterion domain.<br/>
'''is_implementors_of'''<br/>
'''Syntax:''' is_implementors_of {domain}<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature is an implementer of some features listed in criterion domain.<br/>
'''return_type_is'''<br/>
'''Syntax:''' return_type_is {domain}<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if associated class of the return type of the candidate feature is listed in criterion domain.<br/>
==Value Criterion==
''' value_of_metric_is'''<br/>
'''Syntax:''' value_of_metric_is '''Metric''', {domain}, value_tester<br/>
''' Applicable on:''' Target, Group, Class, Generic, Feature, Assertion, Argument, Local, Line<br/>
'''Remark:'''The '''Metric''' modifier will be a specified metric name. This criterion will evaluate to True if the calculated metric (from metric modifier) over input domain (from criterion domain) satisfies some given value tester (from value_tester modifier).
For example, if we want to find classes whose code is over 1000 lines, we can create the following metric and run it over input domain {Application target}:
[[Image:value-of-metric-is|Actual semantic for input domain item]]
[[Image:value-tester|Actual semantic for input domain item]]
In the above dialog, you can customize the value_of_metric_is criterion. A metric needs to be specified as well as its input domain. Sometimes, "Delayed item" is set in the input domain meaning that no matter what the current candidate code element is, use it as input domain to the selected metric and calculate that metric to see if it's value satisfies the given value testers which are also set in this dialog.
You can specify more than one value tester and they can be anded (when "Match all" is selected) or ored (when "Match any" is selected). if no value tester is set, the value_of_metric_is criterion always evaluates to True.
This metric reads, for every class from application target, calculate metric '''Lines of code''' over that class (this is the usage of "Delayed item"), and if the value of '''Lines of code''' over that class is larger than 1000, that class satisfies the '''value_of_metric_is''' criterion thus it's included in the result.
Let's see another example of value_of_metric_is criterion which is more complicated and involves the use of the "Use external delayed domain" option.
Suppose we are to construct a metric called '''Unused features''' which can finds unused features. First, it must be a feature metric because we want features in the result. Second, for every feature candidate, we want a predicate which evaluates to True if that candidate feature is not called by any feature.
And this predicate is semantically equal to say: count all callers of the candidate feature and check if the value is zero. So now, we realize that we need a metric which returns the number of callers of a given feature.
We can construct this feature metric as follows:
[[Image:callee-is|value criterion]]
Let's call it "callee_is" (note: here callee_is is a metric name instead of a criterion name). It uses "Delayed item" because we want that "Delayed item" to be replaced by the actual candidate feature at run-time.
Then we can construct our '''Unused features''' metric as follows:
[[Image:unused-feature|value criterion]]
[[Image:unused-feature-criterion|value criterion]]
In this dialog, note that the "Use external delayed domain" option is checked. It has to be checked. Let's see why.
This value_of_metric_is criterion should check this: for every candidate feature, test if the number of callers of that feature in current application target scope is zero.
Suppose now a feature named foo is the candidate feature.
If the "Use external delayed domain" is not checked, then the metric '''callee_is''' is calculated over input domain {application target}.
So when calculate callee_is metric, every feature (let's call the current candidate feature <eiffel>APPLICATION</eiffel>.<eiffel>goo</eiffel>) from current application target is checked to see if it satisfies the criterion: callee_is {<eiffel>APPLICATION</eiffel>.<eiffel>goo</eiffel>} (the "Delayed item" is replaced by the current candidate feature). This is actually checking if a feature is called by itself.
As you can see, if "Use external delayed domain" option is not checked, during the period of value_of_metric_is criterion evaluation, the current feature candidate from the '''Unused features''' metrics is never involved. This of course yields wrong result.
Now we select the "Use external delayed domain" option. Recall that current candidate feature of metric '''Unused features''' is <eiffel>APPLICATION</eiffel>.<eiffel>foo</eiffel>.
When the value_of_metric_is criterion is evaluated, the delayed item from metric '''callee_is''' is replaced by <eiffel>APPLICATION</eiffel>.<eiffel>foo</eiffel>. So the metric '''callee_is''' now is equal to:
[[Image:fake-callee-is|value criterion]]
which reads: calculate the number of callers of feature <eiffel>APPLICATION</eiffel>.<eiffel>foo</eiffel>. And the value_of_metric_is criterion is now semantically equal to: test if number of callers of <eiffel>APPLICATION</eiffel>.<eiffel>foo</eiffel> is zero. This is what we want.
As we can see, when the option "Use external delayed domain" is selected, the delayed item from the criterion metric will be replaced by the current candidate code element. Otherwise, it will be replaced by the candidate element from criterion metric input domain when criterion metric is calculated.
==Normal Criterion==
'''false'''<br/>
'''Syntax:''' false<br/>
'''Applicable on:''' Target, Group, Class, Generic, Feature, Assertion, Argument, Local, Line<br/>
'''Remark:''' This criterion will always evaluate to False.<br/>
'''has_argument'''<br/>
'''Syntax:''' has_argument<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature has arguments.<br/>
'''has_assertion'''<br/>
'''Syntax:''' has_assertion<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature has any precondition or postcondition.<br/>
'''has_assigner'''<br/>
'''Syntax:''' has_assigner<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature (must be an attribute then) has assigner.<br/>
'''has_bottom_indexing'''<br/>
'''Syntax:''' has_bottom_indexing<br/>
'''Applicable on:''' Class<br/>
'''Remark:''' This criterion will evaluate to True if candidate class has bottom indexing. <br/>
'''has_comment'''<br/>
'''Syntax:''' has_comment<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if candidate feature has header comment.<br/>
'''has_constraint'''<br/>
'''Syntax:''' has_constraint<br/>
'''Applicable on:''' Generic<br/>
'''Remark:''' This criterion will evaluate to True if the candidate generic has constraint.<br/>
'''has_creation_constraint'''<br/>
'''Syntax:''' has_creation_constraint<br/>
'''Applicable on:''' Generic<br/>
'''Remark:''' This criterion will evaluate to True if the candidate generic has creation constraint<br/>
'''has_expression'''<br/>
'''Syntax:''' has_expression<br/>
'''Applicable on:''' Assertion<br/>
'''Remark:''' This criterion will evaluate to True if the candidate assertion has associated expression.<br/>
'''has_indexing'''<br/>
'''Syntax:''' has_indexing<br/>
'''Applicable on:''' Class, Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate class or feature has indexing clause.<br/>
'''has_immediate_invariant'''<br/>
'''Syntax:''' has_immediate_invariant<br/>
'''Applicable on:''' Class<br/>
'''Remark:''' This criterion will evaluate to True if the candidate class has immediate invariant clause (not inherited invariant clause).<br/>
'''has_local'''<br/>
'''Syntax:''' has_local<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature has locals defined in it.<br/>
'''has_postcondition'''<br/>
'''Syntax:''' has_postcondition<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature has immediate postconditions.<br/>
'''has_precondition'''<br/>
'''Syntax:''' has_precondition<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature has immediate preconditions.<br/>
'''has_rescue'''<br/>
'''Syntax:''' has_rescue<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature has rescue clause.<br/>
'''has_tag'''<br/>
'''Syntax:''' has_tag<br/>
'''Applicable on:''' Assertion<br/>
'''Remark:''' This criterion will evaluate to True if the candidate has a descriptive tag associated with it.<br/>
'''has_top_indexing'''<br/>
'''Syntax:''' has_top_indexing<br/>
'''Applicable on:''' Class<br/>
'''Remark:''' This criterion will evaluate to True if the candidate class has top indexing clause.<br/>
'''is_always_compiled'''<br/>
'''Syntax:''' is_always_compiled<br/>
'''Applicable on:''' Class<br/>
'''Remark:''' This criterion will evaluate to True if the candidate class is an always compiled class. Some basic class such as <eiffel>INTEGER</eiffel>, <eiffel>REAL</eiffel> are always compiled no matter whether they are used in an application. These class will cause is_always_compiled criterion evaluate to True.<br/>
'''is_assembly'''<br/>
'''Syntax:''' is_assembly<br/>
'''Applicable on:''' Group<br/>
'''Remark:''' This criterion will evaluate to True if the candidate group is an assembly.<br/>
'''is_attribute'''<br/>
'''Syntax:''' is_attribute<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature is an attribute.<br/>
'''is_blank'''<br/>
'''Syntax:''' is_blank<br/>
'''Applicable on:''' Line<br/>
'''Remark:''' This criterion will evaluate to True if the candidate line is blank.<br/>
'''is_cluster'''<br/>
'''Syntax:''' is_cluster<br/>
'''Applicable on:''' Group<br/>
'''Remark:''' This criterion will evaluate to True if the candidate group is a cluster.<br/>
'''is_command'''<br/>
'''Syntax:''' is_command<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature is a command.<br/>
'''is_comment'''<br/>
'''Syntax:''' is_comment<br/>
'''Applicable on:''' Line<br/>
'''Remark:''' This criterion will evaluate to True if the candidate line is comment line.<br/>
'''is_compiled'''<br/>
'''Syntax:''' is_compiled<br/>
'''Applicable on:''' Target, Group, Class, Generic, Feature, Assertion, Argument, Local, Line<br/>
'''Remark:''' This criterion will evaluate to True if the candidate code element is compiled. Target, group are considered to be compiled once they are referenced by the application. Class (if it is not an always-compiled class) is considered to be compiled if it's used somewhere in the application. always-compiled class are always compiled. and the compilation status of generic, feature, assertion, argument local and line are determined by the compilation status of their written in class.<br/>
'''is_constant'''<br/>
'''Syntax:''' is_constant<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature is a constant.<br/>
'''is_creator'''<br/>
'''Syntax:''' is_creator<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature is a creator feature.<br/>
'''is_deferred'''<br/>
'''Syntax:''' is_deferred<br/>
'''Applicable on:''' Class, Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature is deferred<br/>
'''is_effective'''<br/>
'''Syntax:''' is_effective<br/>
'''Applicable on:''' Class, Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate class or feature is effective.<br/>
'''is_ensure'''<br/>
'''Syntax:''' is_ensure<br/>
'''Applicable on:''' Assertion<br/>
'''Remark:''' This criterion will evaluate to True if the candidate assertion is in ensure clause.<br/>
'''is_ensure_then'''<br/>
'''Syntax:''' is_ensure_then<br/>
'''Applicable on:''' Assertion<br/>
'''Remark:''' This criterion will evaluate to True if the candidate assertion is in ensure then clause.<br/>
'''is_enum'''<br/>
'''Syntax:''' is_enum<br/>
'''Applicable on:''' Class<br/>
'''Remark:''' This criterion will evaluate to True if the candidate class is an enumeration. Only has effect on .NET platform, on other platforms, this criterion always evaluates to False.<br/>
'''is_expanded'''<br/>
'''Syntax:''' is_expanded<br/>
'''Applicable on:''' Class, Generic<br/>
'''Remark:''' This criterion will evaluate to True if the candidate class or generic is expanded.<br/>
'''is_exported'''<br/>
'''Syntax:''' is_exported<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature is exported to ANY.<br/>
'''is_external'''<br/>
'''Syntax:''' is_external<br/>
'''Applicable on:''' Class, Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate class or feature is external.<br/>
'''is_feature'''<br/>
'''Syntax:''' is_feature<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature is real feature. In metrics tool, invariant is treated as a special kind of feature. So if you count features in a class, it's invariant clause will be included. is_feature criterion is used to filter invariant clause out.<br/>
'''is_from_any'''<br/>
'''Syntax:''' is_from_any<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature is from class <eiffel>ANY</eiffel>.<br/>
'''is_frozen'''<br/>
'''Syntax:''' is_frozen<br/>
'''Applicable on:''' Class, Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature is frozen.<br/>
'''is_function'''<br/>
'''Syntax:''' is_function<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate is a function.<br/>
'''is_generic'''<br/>
'''Syntax:''' is_generic<br/>
'''Applicable on:''' Class<br/>
'''Remark:''' This criterion will evaluate to True if the candidate class is a generic class.<br/>
'''is_hidden'''<br/>
'''Syntax:''' is_hidden<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature is exported to <eiffel>NONE</eiffel>.<br/>
'''is_immediate'''<br/>
'''Syntax:''' is_immediate<br/>
'''Applicable on:''' Feature, Assertion, Argument, Local<br/>
'''Remark:''' This criterion will evaluate to True if the candidate code element is immediate instead of inherited.<br/>
'''is_implementation_comment'''<br/>
'''Syntax:''' is_implementation_comment<br/>
'''Applicable on:''' Line<br/>
'''Remark:''' This criterion will evaluate to True if the candidate line is implementation comment. Implementation comment is also called commented code. In Eiffel, the convention is that if the comment indicator "--" starts from the first column of a line, that line is an implementation comment line.<br/>
'''is_infix'''<br/>
'''Syntax:''' is_infix<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature is infix.<br/>
'''is_invariant'''<br/>
'''Syntax:''' is_invariant<br/>
'''Applicable on:''' Assertion<br/>
'''Remark:''' This criterion will evaluate to True if the candidate assertion is from invariant clause.<br/>
'''is_invariant_feature'''<br/>
'''Syntax:''' is_invariant_feature<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature is an invariant. See the description of criterion is_feature for more detail.<br/>
'''is_library'''<br/>
'''Syntax:''' is_library<br/>
'''Applicable on:''' Group<br/>
'''Remark:''' This criterion will evaluate to True if the candidate group is a library.<br/>
'''is_obsolete'''<br/>
'''Syntax:''' is_obsolete<br/>
'''Applicable on:''' Class, Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate class or feature is obsolete.<br/>
'''is_once'''<br/>
'''Syntax:''' is_once<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature is once.<br/>
'''is_origin'''<br/>
'''Syntax:''' is_origin<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature is origin instead of a inherited one.<br/>
'''is_override'''<br/>
'''Syntax:''' is_override<br/>
'''Applicable on:''' Group<br/>
'''Remark:''' This criterion will evaluate to True if the candidate group overrides some other group.<br/>
'''is_overriden'''<br/>
'''Syntax:''' is_overriden<br/>
'''Applicable on:''' Class<br/>
'''Remark:''' This criterion will evaluate to True if the candidate class is overridden by some other class.<br/>
'''is_overrider'''<br/>
'''Syntax:''' is_overrider<br/>
'''Applicable on:''' Class<br/>
'''Remark:''' This criterion will evaluate to True if the candidate class overrides some other class.<br/>
'''is_partial'''<br/>
'''Syntax:''' is_partial<br/>
'''Applicable on:''' Class<br/>
'''Remark:''' This criterion will evaluate to True if the candidate class is partical class. Only has effect on .NET platform, on other platforms, this criterion always evaluates to False.<br/>
'''is_postcondition'''<br/>
'''Syntax:''' is_postcondition<br/>
'''Applicable on:''' Assertion<br/>
'''Remark:''' This criterion will evaluate to True if the candidate assertion is a postcondition.<br/>
'''is_precompiled'''<br/>
'''Syntax:''' is_precompiled<br/>
'''Applicable on:''' Class<br/>
'''Remark:''' This criterion will evaluate to True if the candidate class is precompiled.<br/>
'''is_precondition'''<br/>
'''Syntax:''' is_precondition<br/>
'''Applicable on:''' Assertion<br/>
'''Remark:''' This criterion will evaluate to True if the candidate assertion is a precondition.<br/>
'''is_prefix'''<br/>
'''Syntax:''' is_prefix<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate is a prefix.<br/>
'''is_procedure'''<br/>
'''Syntax:''' is_procedure<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature is a procedure.<br/>
'''is_query'''<br/>
'''Syntax:''' is_query<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature is a query.<br/>
'''is_read_only'''<br/>
'''Syntax:''' is_read_only<br/>
'''Applicable on:''' Class <br/>
'''Remark:''' This criterion will evaluate to True if the candidate class is read-only.<br/>
'''is_reference'''<br/>
'''Syntax:''' is_reference<br/>
'''Applicable on:''' Generic<br/>
'''Remark:''' This criterion will evaluate to True if the candidate generic is reference.<br/>
'''is_require'''<br/>
'''Syntax:''' is_require<br/>
'''Applicable on:''' Assertion<br/>
'''Remark:''' This criterion will evaluate to True if the candidate assertion is in require clause.<br/>
'''is_require_else'''<br/>
'''Syntax:''' is_require_else<br/>
'''Applicable on:''' Assertion<br/>
'''Remark:''' This criterion will evaluate to True if the candidate assertion is in require else clause.<br/>
'''is_satisfied_by'''<br/>
'''Syntax:''' is_satisfied_by command specification<br/>
'''Applicable on:''' Target, Group, Class, Generic, Feature, Assertion, Argument, Local, Line<br/>
'''Remark:'''
This criterion will invoke external command given in command specification to decide whether current item is evaluated to True. Placeholders are used as interface between current item and the external command. The following placeholders are supported:
* $class_name: this will be replaced by class name of current item
* $directory_name: this will be replaced by the directory location of current item
* $file: this will be replaced by file name part, i.e., without heading directory, of $path of current item
* $file_name: this will be replaced by the path of current item
* $f_code: this will be replaced by the F_code directory of current target, if defined
* $group_directory: this will be replaced by the directory of the group of current item
* $group_name: this will be replaced by the group name of current item
* $path: same as $file_name
* $project_directory: this will be replaced by the directory of current project, if defined
* $target_directory: this will be replaced by the directory of current target, if defined
* $target_name: this will be replaced by name of current target, if defined
* $w_code: this will be replaced by the W_code directory of current target, if defined
Command specification can be set in the dialog associated to this criterion, shown in the following picture: [[Image:is-satisfied-by|system hierarchy]]
'''Command name'''<br/>
External command is specified here. <br/>
The command shown in the picture will test the subversion status of the current class (suppose we are running a class metric). The class path is given by "$path". And the output of the "svn stat $path" command is redirected to grep so we can check if the output starts with a letter "M" which indicates tha the class is changed locally.
'''Workding directory'''<br/>
Working directory for the command is set here.
'''Input'''<br/>
Input, if any, of the command is set here. <br/>
If the option "As file name" is checked, the text specified is treated as a file name in which actual input is stored.
'''Output'''<br/>
Expected output, if any, of the command is set here.<br/>
If the option "As file name" is checked, the text specified is treated as a file name in which actual output is stored.<br/>
If the option "Enabled" is not checked, the output will be ignored.
'''Error'''<br/>
Expected error, if any, of the command is set here. <br/>
If the option "As file name" is checked, the text specified is treated as a file name in which actual error is stored. <br/>
If the option "Enabled" is not checked, the error will be ignored.<br/>
If the option "Redirected to output" is checked, error of the command will be redirected to output.
'''Exit code'''<br/>
Expected exit code of the command is set here.<br/>
If the option "Enabled" is not checked, the exit code will be ignored.<br/>
In the above output, error, exit code sections, if more than one are enabled, they are treated as "and-ed". For example if output and exit code are enabled, this criterion is evaluated to True only if the actual output from the command matches the expected output and the exit code from the command matches the expected exit code.
'''is_unique'''<br/>
'''Syntax:''' is_unique<br/>
'''Applicable on:''' Feature<br/>
'''Remark:''' This criterion will evaluate to True if the candidate feature is an unique feature.<br/>
'''is_used'''<br/>
'''Syntax:''' is_used<br/>
'''Applicable on:''' Local<br/>
'''Remark:''' This criterion will evaluate to True if the candidate local is used.<br/>
'''is_used_in_library'''<br/>
'''Syntax:''' is_used_in_library<br/>
'''Applicable on:''' Group<br/>
'''Remark:''' This criterion will evaluate to True if the candidate group is used in some library instead of only referenced by current application.<br/>
'''is_visible'''<br/>
'''Syntax:''' is_visible<br/>
'''Applicable on:''' Class, Generic, Feature, Assertion, Argument, Local<br/>
'''Remark:''' This criterion will evaluate to True if the candidate code element is visible from the input domain of current calculated metric.<br/>
Visibility of a class means that if that element is visible from the input domain of the metric. To explains it more clearly, let's see an example: <br/>
[[Image:system-hierarchy|system hierarchy]]
The figure shows the group hierarchy of a Vision2 application. library <eiffel>base</eiffel> and <eiffel>vision2</eiffel> are used by the application. And notice that library <eiffel>wel</eiffel> is used internally by <eiffel>vision2</eiffel> library but not by the application. This means that classes defined in <eiffel>wel</eiffel> library is not visible to the application thus one cannot use those <eiffel>wel</eiffel> classes in application.
And if we create the following basic metric and run it with current application target as input domain:
[[Image:visible-metric|visible]]
We'll get all classes in the application including those classes in <eiffel>wel</eiffel> library because every class is descendant of class <eiffel>ANY</eiffel>.
But if we do things a little bit differently, we create the following metric and run it with current application target as input domain:
[[Image:visible-metric2|visible]]
Then we will get all visible classes in current application target. i.e., those classes in <eiffel>wel</eiffel> library (any maybe some other invisible classes as well) are filtered out.
Visibility of a generic, feature, assertion, argument, local is determined by its written in class.
'''true'''<br/>
'''Syntax:''' true<br/>
'''Applicable on:''' Target, Group, Class, Generic, Feature, Assertion, Argument, Local, Line<br/>
'''Remark:''' This criterion always evaluates to True.<br/>

64
documentation/17.01/eiffelstudio/eiffelstudio-reference/metrics-tool/definitions/domains.wiki Normal file
View File

@@ -0,0 +1,64 @@
[[Property:title|Domains]]
[[Property:weight|9]]
[[Property:uuid|128ecc21-9d82-d590-fc3e-d0fe52991ac1]]
A domain is a list of code elements, it can contain different kinds of code elements. A domain is used as input to a metric, as output of a metric to review some details, and as an argument passed to some criteria. Domain is used to specify scope.
==Domain Convention==
Before we go to real domain examples, we introduce a simple convention to describe a domain:
* Group element is written in lower case, for example: <eiffel>base</eiffel>, <eiffel>thread</eiffel>
* Class element is written in UPPER case, for example: <eiffel>ANY</eiffel>, <eiffel>LINKED_LIST</eiffel>
* Feature element is written in <eiffel>CLASS_NAME</eiffel>.<eiffel>feature_name</eiffel>, i.e, its associated class will be presented also in upper case and the feature name will be in lower case. For example, <eiffel>ANY</eiffel>.<eiffel>is_equal</eiffel>, <eiffel>STRING_8</eiffel>.<eiffel>is_equal</eiffel>
* All items in a domain will be in curly braces
For example, {<eiffel>ANY</eiffel>, <eiffel>STRING_8</eiffel>.<eiffel>as_lower</eiffel>, <eiffel>base</eiffel>} defines a domain with 3 elements, a class <eiffel>ANY</eiffel>, a feature <eiffel>as_lower</eiffel> which is in class <eiffel>STRING_8</eiffel>, and a group <eiffel>base</eiffel>.
Suppose we have a basic metric called '''Classes''' which counts the number of classes. Before calculating the metric, we need to specify an input domain. This input domain tells metrics system over which scope the metric is calculated. And after calculating a basic metric, for sometimes, we not only want to know the value of that metric, but we are also interested in which are the actual items that adds up to that value. This detailed item list is also accessible for a basic metric if detailed results are specified to be kept before metric calculation, and it is called output domain.
==Domain Examples==
As a real example, go to Metrics tool in EiffelStudio, select Metric Evaluation panel, select metric '''Classes''' in the "Select metric" area, and set input domain in the "Setup input domain" area. See the following figure, in which the input domain is set to {<eiffel>base</eiffel>, <eiffel>APPLICATION</eiffel>}.
[[Image:domain-example1|Defining an input domain]]
After running the metric, you should see the following result in the Detailed Result panel shown in the following figure:
[[Image:domain-example2|Metric detailed result]]
{{note|an element can appear more than one time in a domain, but the detailed result list show only distinct items, so it is possible that the calculated metric value is not equal to the number of items in the detailed result list.}}
A domain can be used as an argument of a relation criterion, see the following example:
[[Image:domain-example3|Domain criterion]]
Here, we define a class basic metric, and in the definition area, we specify a criterion named ancestor_is which is a relation criterion. In that criterion, we set a domain {<eiffel>ANY</eiffel>} as its criterion domain. This metric reads: Count classes whose ancestor is class <eiffel>ANY</eiffel>. Put another way, this metric will find descendants of class <eiffel>ANY</eiffel>.
Now, let's have a look at some examples using delayed item and input domain item.
Suppose we have the following feature metric created in the following figure:
[[Image:domain-example4|Delayed domain item]]
When this metric is calculated over input domain {<eiffel>APPLICCATION</eiffel>}, this means that for every feature from class <eiffel>APPLICATIOIN</eiffel>, we check if it satisfies the defined criterion which is callee_is {Delayed item}. And because of this delayed item, the actual semantic is: For a feature from class <eiffel>APPLICATION</eiffel>, say <eiffel>foo</eiffel>, check if foo satisfies criterion callee_is {<eiffel>APPLICATION</eiffel>.<eiffel>foo</eiffel>}. i.e., the delayed item is replaced by the actual candidate feature.
One may wonder why the concept of delayed item is useful. The answer is that it is powerful when used with other criteria, such as criterion value_of_metric_is. See documentation of value_of_metric_is for details.
Now, an example of Input domain item. Suppose we created the following class basic metric in the following figure:
[[Image:domain-example5|Input domain item]]
And when this metric is calculated over input domain {<eiffel>APPLICATION</eiffel>}, the domain criterion Input domain in ancestor_is criterion will be replaced by the specified input domain, i.e., {<eiffel>APPLICATION</eiffel>}, and the metric will use the current application target as its input domain instead. Put another way, the metric is semantically equal to the following one shown in the following figure:
[[Image:domain-example6|Actual semantic for input domain item]]
{{note|Only code element target, group, folder, class, feature, delayed item, input domain item and application target can be specified through domain selector in Metrics tool. And code element generic, assertion, argument, local, line cannot be specified in domain selector, but they may present in the detailed result domain list.}}
{{seealso|<br/>
[[Units|Units]] <br/>
[[Scopes|Scopes]] }}

36
documentation/17.01/eiffelstudio/eiffelstudio-reference/metrics-tool/definitions/elementary-and-composite-metrics.wiki Normal file
View File

@@ -0,0 +1,36 @@
[[Property:title|Elementary and composite metrics]]
[[Property:weight|4]]
[[Property:uuid|ef89f3c3-180e-3390-74b5-d6d537921453]]
Some of our metrics will be elementary and some composite. An elementary metric is measured directly from the product or a project record:
{{definition|Elementary product metric, elementary process metric|<br/>
- An '''elementary product metric''' is a product metric whose values (integers) indicate the number of occurrences of a certain pattern in a product. <br/>
- An '''elementary process metric''' is a process metric whose values reflect measurements drawn directly from project records. }}
An example of elementary product metric is the number of source lines. An example of elementary process metric is the number of incremental compilations of a system.
Elementary metrics are provided by default by the metric tool. There is no means to remove them or to define new ones since they are not expressed as a combination of other metrics.
From these elementary metrics we may define composite ones:
{{definition|Composite metric|A '''composite metric''' is a metric whose values are defined by a mathematical formula involving other metrics (elementary, or previously defined composite metrics). }}
A later section will introduce a number of operations for defining composite metrics out of elementary ones.
Again we may distinguish between product and process:
{{definition|Composite product metric, composite process metric|<br/>
- A '''composite product metric''' is a composite metric defined entirely in terms of product metrics. <br/>
- A '''composite process metric''' is a composite metric whose definition involves one or more process metrics. }}
By convention, this definition treats as process metric as a composite metric involving both product and process components.
The classification introduced for metrics extends to measures, so that we may talk about an elementary product measure, a composite process measure and so on.
{{seealso|<br/>
[[Attributes, metrics and measures|Metrics]] <br/>
[[Scopes|Scopes]] <br/>
[[Domains|Domains]] <br/>
[[Selection Criteria|Selection criteria]] }}

7
documentation/17.01/eiffelstudio/eiffelstudio-reference/metrics-tool/definitions/index.wiki Normal file
View File

@@ -0,0 +1,7 @@
[[Property:title|Definitions]]
[[Property:weight|2]]
[[Property:uuid|a562c37f-843c-cbbc-def5-32cda604f269]]
The metric tool needs a consistent metric theory on which to rely. Indeed, metrics are notoriously subject to abuse and we must be really accurate when defining metrics and related notions.
This section introduces a set of definitions essential to handle the metric tool.

24
documentation/17.01/eiffelstudio/eiffelstudio-reference/metrics-tool/definitions/measurement-archive.wiki Normal file
View File

@@ -0,0 +1,24 @@
[[Property:title|Measurement archive]]
[[Property:weight|10]]
[[Property:uuid|e1e3e779-e4ca-faee-12b5-f47c8adde174]]
If you want to perform measurements on a system that you are building, the scopes of interest are the first four listed: Feature, Class, Cluster and System. Information on either of these scopes will be provided by the development environment (as with EiffelStudio 5.x); alternatively, you could get it simply by parsing the source of your system. But what if you also need quantitative data on other systems, if only for purposes of seeing how your results compare to the quantitative properties of other people's work?
It would be impractical in this case to require tools that have access to as much information on external systems as on your own. All we really need is a record of previous measurements on these systems. This explains the fifth scope type, Archive: beyond the scope of the current system, all we require to define a scope is a '''measurement archive''', or just "archive" for short. This is simply a file (or part of a file) that retains, in a suitable format (XML-based), the results of measurements made earlier on one system. The file can be local or accessible as a URL on the Internet.
The ability to use a measurement archive as a scope means that:
* A project may set up a measurement archive as the record of its measures.
* A department or company may set up a measurement archive for all projects on which it keeps metric information.
* The provider of the development environment, such as Eiffel Software, may publish a set of measurement archives giving metric information for reference projects, such as the EiffelBase library (designed in part as a showcase of Eiffel technology). Eiffle Software indeed intends to include a '''metrics''' directory, with a set of measurement archives for reference tools and libraries, in forthcoming releases of EiffelStudio and at [http://www.eiffel.com/ http://www.eiffel.com/] .
The metric tool provides an easy way to create, update or compare archives in the Metric Archive tab. Simply select tab archives.
The metric tool automatically creates a sub folder named "Metrics" in the current location of the loaded project. It is recommended, but not compulsory, to save created archives in that folder, since it has been provided for metric needs.
<span></span>
We hope that once the facilities described here are available users will adopt the practice of publishing measurement archives; it's a way of providing quantitative reference information, useful to everyone, without revealing anything critical about the actual contents of the software. (For further protection one may envision an independent group that anonymizes the data after verifying the authenticity of the source.)

25
documentation/17.01/eiffelstudio/eiffelstudio-reference/metrics-tool/definitions/metric-framework-and-theory.wiki Normal file
View File

@@ -0,0 +1,25 @@
[[Property:title|Metric framework and theory]]
[[Property:weight|3]]
[[Property:uuid|5e76bd87-b7a7-8307-0e9e-ca9bb31db0f9]]
You will want to rely not on a single metric but on a combination of metrics:
{{definition|Metric framework|A '''metric framework''' is a set of definitions of metrics. }}
Any metric work should be backed by a theory:
{{definition|Metric theory|A '''metric theory''' is a combination of: <br/>
- A metric framework <br/>
- A set of definitions of attributes (qualitative or quantitative) <br/>
- A mapping from the framework to the set of attributes, representing the hypothesis that each metric is a good predictor of the associated attribute }}
This note does not introduce a metric theory, but defines a metric framework by introducing a number of metrics.
{{seealso|<br/>
[[Attributes, metrics and measures|Attributes, metrics and measures]] }}

197
documentation/17.01/eiffelstudio/eiffelstudio-reference/metrics-tool/definitions/predefined-raw-metrics.wiki Normal file
View File

@@ -0,0 +1,197 @@
[[Property:title|Predefined raw metrics]]
[[Property:weight|7]]
[[Property:uuid|12906fea-78e3-3539-27d7-83662829b59e]]
The environment should make it possible, for any project, to apply the elementary metrics in the following table, each with an associated unit and a one-identifier name. Each of the major divisions of the table starts with a raw metric, for example Classes, and, when appropriate, continues with selection criteria that yield derived metrics based on that raw metric, for example Deferred_classes.
{|
|-
| '''Basic Count'''
| '''Criterion'''
| '''What to count'''
| '''Unit'''
|-
| Classes
|
| Classes of a cluster or system
| Class
|-
| Deferred
| Deferred classes (not completely implemented, as opposed to "effective", completely implemented).
|-
| Invariant equipped
| Classes having an invariant
|-
| Obsolete
| Classes marked as superseded by newer alternatives
|-
| Dependents
|
| Classes on which a class depends, directly or indirectly
| Class
|-
| Clients
| Direct clients
|-
| Heirs
| Direct heirs in inheritance structure
|-
| Parents
| Direct parents in inheritance structure
|-
| Suppliers
| Direct suppliers
|-
| Indirect clients
| Indirect clients
|-
| Indirect heirs
| Indirect heirs in inheritance structure
|-
| Indirect parents
| Indirect parents in inheritance structure
|-
| Indirect suppliers
| Indirect suppliers
|-
| Self
| The class itself (value always 1)
|-
| Groups
|
| Groups of a system or sub-clusters of a cluster
| Group
|-
| Compilations
|
| Compilations since start of project
| Compilation
|-
| All features
|
| Inherited and immediate features of a class
| Feature
|-
| Attributes
| Attributes (features represented by fields in instances of the class, as opposed to routines, represented by algorithms)
|-
| Deferred
| Deferred routines (not implemented, as opposed to effective features, which are implemented)
|-
| Exported
| Features available to all clients
|-
| Functions
| Value-returning routines
|-
| Postcondition equipped
| Routines having a postcondition
|-
| Precondition equipped
| Routines having a precondition
|-
| Queries
| Value-returning features, including both attributes and functions (routines returning a result, as opposed to procedures)
|-
| Inherited
| Features obtained from a parent (possibly in a different form)
|-
| Immediate features
|
| Immediate features of a class
| Feature
|-
| Attributes
| Attributes (features represented by fields in instances of the class, as opposed to routines, represented by algorithms)
|-
| Deferred
| Deferred routines (not implemented, as opposed to effective features, which are implemented)
|-
| Exported
| Features available to all clients
|-
| Functions
| Value-returning routines
|-
| Postcondition equipped
| Routines having a postcondition
|-
| Precondition equipped
| Routines having a precondition
|-
| Queries
| Value-returning features, including both attributes and functions (routines returning a result, as opposed to procedures)
|-
| All feature assertions
|
| Clauses in routine's assertion, whether inherited or not
| Assertion
|-
| Postcondition clauses
| Clauses in postcondition
|-
| Precondition clauses
| Clauses in precondition
|-
| Immediate feature assertions
|
| Clauses in routine's assertion, not inherited
| Assertion
|-
| Postcondition clauses
| Clauses in postcondition
|-
| Precondition clauses
| Clauses in precondition
|-
| Invariant clauses
|
| Clauses in invariant
| Assertion
|-
| Formal generics
|
| Formal generic parameters of a class
| Generic
|-
| Constrained
| Formal parameters constrained by a type other than ANY
|-
| All formals
|
| Formal argument of a routine whether inherited or not
| Local
|-
| Immediate formals
|
| Formal argument of a routine.
| Local
|-
| Lines
|
| Source lines
| Line
|-
| All locals
|
| Local entities of feature whether inherited or not (excluding Result)
| Local
|-
| Immediate locals
|
| Local entities of feature (excluding Result)
| Local
|}
A few comments on specific entries:
* The list of criteria for Features does not include Routines because a routine is a feature that is not an attribute; to obtain the number of routines, just count features that do not satisfy the Attributes criterion.
* The selection criteria Attributes and Deferred for Features are, a noted earlier, not independent, since attributes may not be deferred.
* Another case of dependency: a procedure is never part of Queries but always a command. Queries, however, include both Attributes and Functions.
* Two more cases of dependency: Redeclared and Renamed can only be satisfied for features that are inherited. A feature that is not inherited, but introduced fresh in the enclosing class, is called immediate.
* The Redeclared attribute has three values: a feature is redefined if it was effective in the parent, or it was deferred in the parent and the new class keeps it deferred with a different signature or contract; it is effected if it was deferred and the class makes it effective; or it may be neither of these.
All metrics listed are product metrics with one exception: Compilations, the only process metric, counting the number of compilations of the project. There is room for more process metrics, such as cost estimates; this requires standard formats letting project managers enter the appropriate information, a point that future versions of the metrics policy described here may develop further.
There is also room for elementary product metrics other than those in the preceding table. In fact, every syntactic construct is a candidate for an elementary metric that simply counts the number of its occurrences; but we should limit ourselves to those that we judge interesting. The metrics literature also suggests elementary metrics assessing complexity of the control structure through properties of the control graph (McCabe), or routine coherence through such properties as the number of attributes accessed by a routine; we should only add them if we can find convincing arguments for their theoretical soundness.

48
documentation/17.01/eiffelstudio/eiffelstudio-reference/metrics-tool/definitions/raw-metrics-and-selection-criteria.wiki Normal file
View File

@@ -0,0 +1,48 @@
[[Property:title|Raw metrics and selection criteria]]
[[Property:weight|5]]
[[Property:uuid|99f51fd0-4439-08f5-9419-53c8771b50f8]]
Elementary metrics measure patterns whose occurrences (in a product or process) can be counted. We need to decompose this notion further to avoid an explosion of the number of elementary metrics. For example the features of a class can be classified along several lines:
* Some are attributes (object fields), others are routines (algorithms).
* Some are inherited from a parent, others immediate (defined in the class).
* Some are exported, others secret
and so on. Many combinations of these properties may be worth counting on their own: you may ask for the number of secret attributes, of exported inherited features and so on. But if we define all of these metrics independently, we will soon have too many elementary metrics, while still failing to satisfy user needs if we have omitted a particular combination.
To avoid this we must identify a subset of elementary metrics as '''raw metrics''': metrics whose results are counted directly. "Number of features in a class" is a raw metric. From a raw metric, we may then derive other elementary metrics by applying '''selection criteria''' such as "Is this feature an attribute?" or "Is this feature exported?" Here are the definitions:
{{definition|Raw metric, selection criterion, derived metric|<br/>
An elementary metric is either '''raw''' or '''derived'''. A '''selection criterion''' for a raw metric is a property, with a fixed set of possible values (two or more), characterizing the patterns or events being counted by the metric. <br/>
A '''derived metric''' is an elementary metric defined from a raw metric by counting only the patterns satisfying a certain combination of its selection criteria. }}
A set of raw metrics and selection criteria is provided by default by the metric tool, see [[Predefined raw metrics|predefined raw metrics and selection criteria]]
To define a derived metric, we start from a raw metric, for example "number of features", and combine some of the associated selection criteria. The combination may be:
* An "or": for example, count all the features that are attributes or exported (or both).
* An "and": count all the features that are both attributes and exported.
A selection criterion may have more than two possible values. Most, as in these examples, have just two: a feature is either an attribute or a routine; it is either exported or secret.
The definition states that every derived metric is derived from a certain raw metric or from another derived metric.
As a general guideline, we will try to keep the selection criteria for a given raw metric independent. For example, to distinguish the classes that inherit a given class we will use the following selection criteria:
* Heirs: count the number of direct heirs of a class.
* Indirect_heirs: count the number of indirect heirs.
* Self: count only the class itself.
Other interesting notions are "proper descendant", covering direct and indirect heirs, and "descendant", covering proper descendants and descendants. We do not introduce these as separate criteria, since this would result in a non-independent set of criteria: every proper descendant is a descendant, every heir (direct or indirect) is a proper descendant.
Instead we limit ourselves to the three criteria listed above. If you need a finer decomposition, it is easy, with the techniques discussed below, to define Proper_descendants and Descendants as composite metrics expressed in terms of the elementary metrics Heirs, Indirect_heirs and Self.
This criterion independence principle is not absolute, however, and in some cases we may find it clearer to define a new criterion even though its value is entirely determined by certain values of another. For example one criterion on features determines whether it is an attribute or a routine, another whether it is deferred or effective. An attribute is always effective, so the two criteria are not independent. Even though we could remove the dependency by using a single criterion with three values (attribute, effective routine, deferred routine), it is more convenient to keep two criteria. Of course the underlying counting mechanisms must make sure never to count an element twice even in an "or" query, as when a user asks for the number of features that are attributes or effective.
A metric is either elementary or composite. An elementary metric is either a raw metric, such as "number of features", or a derived metric obtained from slicing a raw metric by selection criteria. Composite metrics are obtained from existing metrics (elementary, or previously defined composite metrics) by applying some mathematical formula.
{{seealso|<br/>
[[Elementary and composite metrics|Elementary metrics]] <br/>
[[Selection Criteria|Selection Criteria]] <br/>
[[Criterion References|Selection criterion reference]] <br/>
[[Defining derived metrics|Defining derived metrics]] }}

28
documentation/17.01/eiffelstudio/eiffelstudio-reference/metrics-tool/definitions/scopes.wiki Normal file
View File

@@ -0,0 +1,28 @@
[[Property:title|Scopes]]
[[Property:weight|8]]
[[Property:uuid|303fb469-9f2b-d7cc-55e7-d657fb87b8fe]]
Every metric has a scope:
{{definition|Scope of a metric|<br/>
The '''scope''' of a metric is defined as follows: <br/>
- For a raw product metric, the type of product over which the metric is counted, such as: a feature, a class, a group, an archive built for a given system to make it possible to compare systems. <br/>
- For a raw process metric, the type of process on which the metric is measured, such as analysis, documentation, entire project etc. <br/>
- For a derived metric (recursively), the scope of the raw metric from which it is derived. <br/>
- For a composite metric (recursively), the largest of the scopes of all its constituent metrics, where cluster is "larger than" class and so on. }}
This notion also applies to measures:
{{definition|Scope of a measure|<br/>
The '''scope''' of a measure is defined as follows: <br/>
- For an elementary measure (the application of an elementary metric, raw or derived), the set of products or processes to which the associated metric has been applied to yield the measure. <br/>
- For a composite measure, the union of (recursively) the scopes of its constituent measures. }}
For both metrics and measures, the notion of scope will help us compare our quantitative assessments to some already on record. For example you may compare the value of a certain metric, such as number of invariant clauses in each class, with the values that have been archived for your project, for a reference project such as the EiffelBase library, for the previous projects of your company, or for a global set of previous projects maintained at some central location. You may also, with appropriate permissions, update such a shared archive with the values from your own measurements.
In the environment, the notion of scope will be handled by defining an input domain. If the input domain contains a duplicated elements, the computation is done twice on the duplicated elements.

116
documentation/17.01/eiffelstudio/eiffelstudio-reference/metrics-tool/definitions/selection-criteria.wiki Normal file
View File

@@ -0,0 +1,116 @@
[[Property:title|Selection Criteria]]
[[Property:weight|6]]
[[Property:uuid|d492c7f5-71ec-ae04-c62b-6845f30ed762]]
A selection criterion is used to filter out candidate code elements and only leave and count those satisfied elements. For example, criterion is_deferred in a basic class metric is only satisfied when a candidate class is deferred. A selection criterion can have modifiers which indicate how the associated criterion will perform its filtering task. There are four kinds of modifiers, shown as follows:
* Text modifier - String text, and this text is called criterion text
* Domain modifier - Domain, and this domain is called criterion domain
* Metric modifier - Metric, and this metric is called criterion metric
* Normal modifier - modifier other than text, domain and metric
Let's first introduce a convention to describe selection criteria:
* Criterion name will be followed by modifiers (separated by a comma) if any
* Text modifier will be in double quotes
* Domain modifier will follow the convention of domain
* Metric modifier will be in bold
* Normal modifier will be in normal font and face
* Braces will be added to avoid ambiguity
Some examples:
is_deferred
text_is "some text", identity, case-sensitive
ancestor_is {<eiffel>ANY</eiffel>}
value_of_metric_is '''Class''', {base}, (>0 and <100)
There are several kinds of selection criteria, namely, text criterion, path criterion, relation criterion, metric value criterion and normal criterion.
==Text Criterion==
Text criterion uses a text modifier, two normal modifiers (one to specify matching strategy and the other to specify case sensitivity) to perform text pattern matching. Criterion such as name_is and text_is are text criteria.
Let's take text criterion name_is as an example:
The syntax for name_is is:
name_is "pattern", matching_strategy, case_sensitive
The match_strategy modifier decides how criterion text "pattern" is matched, and can choose from one of the following four values:
* Identity - Pattern is matched if the text is identical to criterion text
* Containing - Pattern is matched the text contains criterion text
* Wildcard - Pattern is matched if it occurs in criterion text according to wildcard rules
* Regular expression - Pattern is matched if it occurs in criterion text according to regular expression rules
The case_sensitive modifier can be True or False, it indicates if pattern matching is case sensitive or not.
In the following two figures, name_is criterion is shown. That criterion will select all classes whose name starts with a letter A (using regular expression rules) case-insensitively.
[[Image:selection-cri1|Text criterion]]
[[Image:selection-cri2|Text criterion]]
==Path Criterion==
A path criterion uses a text modifier as path to test if a candidate class is located in that path. There are two path criteria, namely, path_is and path_in.
The path uses Unix format. For example, criterion path_is "/kernel" will evaluate to True if a candidate class is located in kernel folder related to the class's group. On Windows, path matching will be case-insensitive, on other platforms, path matching will be case-sensitive.
The following figure shows a path criterion used to find classes which locate in "kernel" folder:
[[Image:selection-cri3|Path criterion]]
==Relation Criterion==
A relation criterion uses a criterion domain to check if a candidate code element is of some relationship between the criterion domain. Some other modifiers may also appear in a relation criterion.
Let's have look at a class relation criterion client_is shown in the following two figures where a basic class metric with relation criterion client_is is defined. This client_is criterion will match all direct normally referenced as well as only syntactically referenced suppliers of class <eiffel>LINKED_LIST</eiffel>.
[[Image:selection-cri4|Relation criterion]]
[[Image:selection-cri5|Relation criterion]]
For more information about normally referenced and only syntactically referenced suppliers, see document of relation criterion client_is.
==Value Criterion==
Value criterion is used to test if calculated value of a given metric satisfies some values. There is only one criterion named value_of_metric_is in this category. Please see the document for value criterion value_of_metric_is for more information.
The following figure shows the use of value_of_metric_is criterion, where a class basic metric is defined to find classes whose lines of code is over 1000:
[[Image:selection-cri6|Relation criterion]]
The following figure shows the result of the above metric:
[[Image:selection-cri7|Relation criterion]]
==Normal Criterion==
All other criteria except for those described above are called normal criteria.
Some examples:
is_library - test if a candidate group is a library
is_deferred - test if a candidate class or feature is deferred
is_comment - test if a candidate line is comment
==Criterion Connector==
There are three criterion connectors: and, or, not. They are self-explanatory. Just a simple example, see the following figure:
[[Image:selection-cri8|Relation criterion]]
{{seealso|<br/>
[[Domains|Domains]] <br/>
[[Criterion References|Selection criterion reference]] }}

52
documentation/17.01/eiffelstudio/eiffelstudio-reference/metrics-tool/definitions/under-hood-how-metrics-work.wiki Normal file
View File

@@ -0,0 +1,52 @@
[[Property:title|Under the Hood - How metrics work]]
[[Property:weight|11]]
[[Property:uuid|4b81b16a-0c46-8d5a-c5b5-346ea01c58ee]]
This part explains how a product basic metric is calculated.
==Domain Transformation==
As you have seen, before calculating a product basic metric, two things have to be specified:
* A metric, and every metric has a unit
* An input domain
And two facts follows:
* the specified metric will count the number of the code elements specified by the metric unit
* An input domain can contain any kinds of code elements
For example, in the following figure, a metric as well as its input domain are specified:
[[Image:hood1|Actual semantic for input domain item]]
Here the selected metric is '''Compiled classes''', and the input domain is {<eiffel>base</eiffel>}, and when calculating, all compiled classes in library base will be found and counted. The result is shown in the following figure:
[[Image:hood2|Actual semantic for input domain item]]
But how are those compiled classes found in library <eiffel>base</eiffel>? The answer is through an operation called domain transformation.
A domain transformation will transform a source domain into a destination domain with a specified product unit. This means that a product unit has to be specified to indicate what kind of code element will appear in a destination domain. A product unit can be one of the following: target, group, class, generic, feature, argument, local, assertion, line.
A domain transformation is done like this: For every code element in source domain, all code elements of the destination unit that can be found (with the help of the compiler) in that source code element are put into the destination domain.
Let's continue to use the above '''Compiled classes''' example. The input domain {<eiffel>base</eiffel>} is source domain, and the result domain of the metric is the destination domain here. The destination unit is class which is the unit of the specified metric '''Compiled classes'''.
So for a source code element (here it is <eiffel>base</eiffel>), find all classes in that element (<eiffel>base</eiffel>), and put them in the destination domain. Now we get a destination domain which contains all candidate classes. Those classes are called candidates because we only want some of them. And the filtering is done with the specified criterion is_compiled. After that, you get the actual result domain.
It's quite easy to understand the group to class transformation. But what if I want some features now? Just do consecutive transformations: from group to class first, and then from class to feature.
We call a transformation from an element to another element a route, consecutive transformations a path. All possible transformation paths are shown in the following figure:
[[Image:hood3|Actual semantic for input domain item]]
Some remarks on the transformation paths:
* If you go through the path from the end of an arrow to its head, you'll possibly find results, but if the transformation is done in the reversed direction, nothing will be found. For example, in any cases, the destination domain will be empty (indicating nothing is found) if you do a transformation from a line element to a class element.
* Code element line appears in the path: Target -> Group -> Class -> Line because typically in an Eiffel class, there are some lines that do not belong to any features, such as class <code>note</code> lines or <code>inherit</code> clauses.
* The shortest path will always be used. So if you transform a target element to a line element, the path: Target -> Group -> Class -> Line will be used instead of Target -> Group -> Class -> Feature -> Line
* Paths from element to the element of the same unit are omitted. i.e., there are paths such as Target -> Target, Group -> Group, Class -> Class
==Domain Filtering==
After domain transformation, we get a destination domain with all candidate code elements. Then we perform a filtering operation using the specified criterion in a basic metric to get rid of all unsatisfied candidates. At last, we'll get the desired result domain. Using the above example, for every class in the destination domain, we test if that class is compiled using the specified criterion is_compiled. If it's a compiled class, keep it in the destination domain, if not, remove it from the destination domain.

137
documentation/17.01/eiffelstudio/eiffelstudio-reference/metrics-tool/definitions/units.wiki Normal file
View File

@@ -0,0 +1,137 @@
[[Property:title|Units]]
[[Property:weight|2]]
[[Property:uuid|fa08d5aa-7ea4-e7bb-bb59-e4982a583976]]
Metrics will be expressed in units, such as Line (numbers of source lines) or Feature (number of features).
{{rule|name=Unit rule|text=The definition of any metric must specify an associated unit. }}
Different metrics may be marked with the same unit; for example metrics such as number of non-comment lines and number of comment lines may both be marked with the unit Line.
Whenever we need to express ratios of one measurement to another, as in computing the average number of features per class by dividing the number of features by the number of classes, we will use a specific unit, Ratio:
{{definition|Ratio unit|The name Ratio denotes a predefined unit, whose values are arbitrary real numbers, expressed either as numbers or in percentage style (as in 35.3%). }}
As a result of this choice, we will consider every division to yield a result of unit, Ratio.
The following predefined units are available in the metric tool:
{|
|-
| '''Unit'''
| '''Quantities measured'''
| '''Kind'''
|-
| Class
| Number of classes or types
| Product
|-
| Generic
| Number of class generics
| Product
|-
| Feature
| Number of features
| Product
|-
| Target
| Number of targets
| Product
|-
| Group
| Number of groups
| Product
|-
| Assertion
| Number of assertion clauses
| Product
|-
| Argument
| Number of arguments of a routine
| Product
|-
| Local
| Number of locals of a routine
| Product
|-
| Line
| Number of source lines
| Product
|-
| Compilation
| Number of compilations
| Process
|-
| Ratio
| Results of divisions
| Product
|}
The units listed here are '''minimal''' in the sense that it is not possible to add the properties measured by any two of them; for example it makes no sense to add a number of features to a number of classes.
In the future, it might be desirable to include more specific units, such as "features per class" , and an associated calculus of units (as in the physical sciences, where multiplying a quantity expressed in g /cm by one in cm yields a result in g). This has not appeared necessary for the typical uses of division envisioned in this note, answering such questions as "What percentage of routines have a header comment" can all be expressed simply as ratio.
==Code Element==
For most of units, an item of that unit represents a code element in a real system. For example, an item of class unit represents a class and an item of line unit represents a line of code. All supported code elements are listed as follows:
{|
|-
| '''Code Element'''
| '''Unit'''
| '''Description'''
|-
| Class
| Class
| Represents a class
|-
| Generic
| Generic
| Represents the piece of the code related to generics definition in a class definition.
|-
| Feature
| Feature
| A feature or an invariant clause. In metrics tool, a feature can be one of two things: a traditional feature, or an invariant clause. That is to say, an invariant clause is treated as a special feature. To avoid ambiguity, we call a traditional feature a "feature" and an invariant clause an "invariant feature".
|-
| Target
| Target
| Represents a target
|-
| Group
| Group
| Represents a group in system. A group can be either a cluster, a library or an assembly
|-
| Assertion
| Assertion
| Represents an assertion
|-
| Argument
| Argument
| Represents a formal argument in features
|-
| Local
| Local
| Represents a local defined in features
|-
| Line
| Line
| Represents a line of code
|-
| Folder
| -
| Represents a physical concept to store classes. The semantic of a folder in metrics tool is equal to a list all classes which are located in that folder (not recursively). So a folder item doesn't provide new functionality, it just facilitates the operation to select a set of classes.
|-
| Delayed item
| -
| A delayed item is a place holder, it will be replaced by the candidate code element over which a domain criterion is evaluated
|-
| Input domain item
| -
| An input domain item is a place holder, it will be replaced by the domain selected as input to the metric. In the case that the input domain is presents in a basic metric definition, when that metric is calculated, the metric will use the current application target as the input domain.
|-
| Current application item
| Target
| Represents the application target of the current Eiffel system
|}

13
documentation/17.01/eiffelstudio/eiffelstudio-reference/metrics-tool/index.wiki Normal file
View File

@@ -0,0 +1,13 @@
[[Property:title|Metrics tool]]
[[Property:weight|-5]]
[[Property:uuid|e76d1c3b-773f-c051-bd94-3272f3ccadc6]]
One of the innovations of the EiffelStudio development environment is a set of metric facilities enabling developers and managers to obtain quantitative information about software systems and the process of producing them.
* Find out basic quantitative properties of a system, such as the number of classes, the number of features, how many times the system has been compiled and many others
* Define new properties as mathematical combinations of the basic ones, and compute the resulting values, to get the answers to such questions as what percentage of my system's routines have precondition clauses' or what is the average number of features, lines, or invariant clauses per class?
* Vary the scope of such measurements, so that the measured result may cover a single feature, a class, a cluster, an entire system or an archive of another system to make comparisons with other projects.
* Compare the result of the same metric over several of these scopes, to see for example how a project differs from those on record, or whether some parts of a project depart from the norms applied in others.
The environment will support such measurements through a simple graphical interface, closely integrated with the rest of the Eiffel Explorer. Users of the environment can start applying these facilities to their systems without learning any theory.
Metrics, however, are notoriously subject to abuse; we must be wary of the temptation to revere numbers just because they are numbers (lies, damn lies and metrics). This note presents a simple approach to software metrics designed to establish a clear and sound basis, so that we know what we are measuring, why we are measuring it, and how much value we may attach to the results.

20
documentation/17.01/eiffelstudio/eiffelstudio-reference/metrics-tool/requirements.wiki Normal file
View File

@@ -0,0 +1,20 @@
[[Property:title|Requirements]]
[[Property:weight|1]]
[[Property:uuid|834b134f-b4a5-08a7-e41c-804c0954b008]]
All engineering disciplines other than software rely on quantitative approaches to design their products, organize the production process, and assess the results. Software engineering too can benefit from measuring relevant properties of its products and processes.
Measurements are not an end in themselves; they must be related to broader goals of software engineering:
The purpose of software measurements is to provide quantitative assessments or predictions of properties of software products and processes
For any numerical measure that we propose we must have precise information on four properties: coverage, trustworthiness, relevance, theory.
Any quantitative report on software products or processes should satisfy the following properties:
* '''Coverage''': include a definition of what is being measured, sufficient to enable repetition of the measurements.
* '''Trustworthiness''': include an estimate of how much the results can be believed, in particular of their precision (expected variations in case of repetition).
* '''Relevance''': specify interesting properties of software products or processes on which the measurement may provide insight.
* '''Theory:''' include arguments backing the statement of relevance.

16
documentation/17.01/eiffelstudio/eiffelstudio-reference/metrics-tool/user-interface-basics/detailed-result-panel.wiki Normal file
View File

@@ -0,0 +1,16 @@
[[Property:title|Detailed Result Panel]]
[[Property:weight|1]]
[[Property:uuid|35018218-cf90-5aca-dc47-205bb351592e]]
The Detailed result panel is where detailed metric result and archive comparison result are displayed. In the following two figures, a detailed metric result and an archive comparison result are shown.
Detailed metric result:
[[Image:interface4|Defining an input domain]]
Archive comparison result:
[[Image:interface5|Defining an input domain]]

5
documentation/17.01/eiffelstudio/eiffelstudio-reference/metrics-tool/user-interface-basics/index.wiki Normal file
View File

@@ -0,0 +1,5 @@
[[Property:title|User interface basics]]
[[Property:weight|3]]
[[Property:uuid|c2b8d8b6-661c-1cb5-a991-388e8374c696]]
EiffelStudio includes a Metric tool based on the previously defined metric theory. This tool provides many facilities like computing measures over a project, including smaller scopes, defining new metrics according to users needs, and handling archives to compare projects.

34
documentation/17.01/eiffelstudio/eiffelstudio-reference/metrics-tool/user-interface-basics/metric-archive-panel.wiki Normal file
View File

@@ -0,0 +1,34 @@
[[Property:title|Metric Archive Panel]]
[[Property:weight|4]]
[[Property:uuid|c8793405-c91d-c04b-10ed-07739728f697]]
The metric archive panel is used to calculate and restore metric archives and to do metric archive comparison.
==Metric Archive Calculation==
Let's have a look at the buttons and options related to metric archive calculataion:
[[Image:metrics-tool--debug-run-icon|calculate archive]] Start metric archive calculation<br/>
After selecting the metrics you want to archive and the input domain, use this button to start a metric archive calculation.
[[Image:metrics-tool--debug-stop-icon|stop archive]] Stop metric archive calculation<br/>
Use this button to stop a metric archive calculation.
[[Image:interface22|archive file location]] Specify archive file<br/>
The file to store metric archive results is specified here.
[[Image:interface23|reset archive]] Reset archive file<br/>
If the specified archive file already contains some archive information, this option will be sensitive. If it's enabled, the information contained in that archive file will be cleaned before new archive information is written to that file, otherwise, new archive information will be appended to that file.
==Metric Archive Comparison==
After you specify two archive files you can compare them, as shown in the following image:
[[Image:interface24|Compare archives]]
The archive comparison result is shown in the following figure:
[[Image:interface25|archive comparison result]]

87
documentation/17.01/eiffelstudio/eiffelstudio-reference/metrics-tool/user-interface-basics/metric-definition-panel.wiki Normal file
View File

@@ -0,0 +1,87 @@
[[Property:title|Metric Definition Panel]]
[[Property:weight|2]]
[[Property:uuid|5a778f15-cefe-182d-a296-545ee77d3028]]
In the metric definition panel, you can do the following:
* Manage user-defined metrics, such as defining new metrics and modify or remove existing ones. Metrics with a small lock in their icons are predefined metrics which cannot be changed or remvoed
* Import metrics from other systems
* Backup user-defined metrics
The following figure shows the layout of the metric definition panel:
[[Image:interface6|Metric definition panel]]
Let's have a look at the buttons in the main toolbar which is highlighted in the following figure:
[[Image:interface7|Main toolbar buttons]]
[[Image:metrics-tool--new-metric-icon|New metric]] New metric
Use this button to create a new metric. First you need to select a metric type (basic, linear or ratio) and then you may need to select a unit (only for basic and linear metrics). Once a metric is created, its unit cannot be changed.
[[Image:metrics-tool--new-document-icon|Clone metric]] Clone selected metric to a new metric
If you want to define a new metric but the new metric is quite similar to an existing one, then you can use this button to simplify your work: just clone an existing one and do the modifications.
[[Image:metrics-tool--general-remove-icon|Remove metric]] Remove metric
Remove current selected metric. This button will be insensitive when the current selected metric is a predefined metric.
[[Image:metrics-tool--general-save-icon|Save metric]] Save metric
To make your newly defined or modified metric take effect, you need to save it first. This button will be insensitive when the current selected metric is a predefined metric.
[[Image:metrics-tool--command-send-to-external-editor-icon|External editor]] Open user-defined metric file in external editor
Metrics are stored in XML format, and this button opens the XML file of user-defined metrics in a an external editor which can be specified in the preferences.
[[Image:metrics-tool--general-open-icon|Reload metrics]] Reload metrics
This button reloads all metrics including predefined and user-defined metrics. It's useful when you modify the metric XML file in an external editor and want the changes to have an effect without restarting EiffelStudio.
[[Image:metrics-tool--metric-export-to-file-icon|import]] Import metrics
This button opens a dialog to backup or import metrics.
==Define New Metrics==
To define a new metric, you need to choose the metric type and unit (for basic metric and linear metric). The following figure shows how to choose metric type and unit:
[[Image:interface8|Choose metric type]]
The following figure shows a new basic class metric:
[[Image:interface9|basic metric]]
When defining basic metrics, you can press <code>CTRL</code>+<code>Space</code> in a cell in the criterion column (the first column in "definition" area) to get a list of all applicable criteria. You can also type "and" or "or" in that cell to get criterion connectors. And you can put "not" in front of a criterion name to get its negation. After typing the criterion name and hitting enter, if the criterion needs further setup, the property cell of that criterion will be highlighted. For domain criterion such as ancestor_is, caller_is, you can pick an item and drop it into this property cell.
The following figure shows a new linear feature metric:
[[Image:interface10|linear metric]]
For every metric referenced in a linear metric, you need to specify a coefficient. You can pick a metric and drop it into a cell of the "Metrics" column in the "Metric Definition" area.
The following figure shows a new ratio metric:
[[Image:interface11|ratio metric]]
For the numerator or denominator metric, you need to specify a coefficient. When the denominator part evaluates to zero, the result of the ratio metric will be "Undefined". You can pick a metric and drop it into the numerator or denominator metric area.
==Import Metrics==
In order to reuse metrics defined in a different system, you need to import them into current system. The following figure shows how to import metrics:
[[Image:interface12|Import metrics]]
==Backup User-defined Metrics==
The following figure shows how to back user-defined metrics:
[[Image:interface13|Backup metrics]]

39
documentation/17.01/eiffelstudio/eiffelstudio-reference/metrics-tool/user-interface-basics/metric-evaluation-panel.wiki Normal file
View File

@@ -0,0 +1,39 @@
[[Property:title|Metric Evaluation Panel]]
[[Property:weight|0]]
[[Property:uuid|c31fddbb-7421-fe4b-57d3-7eea32f5e9e0]]
The Metric Evaluation panel is the place to do metric evaluation. After selecting a metric from the "Select metric" area and setting an input domain in the "Setup input domain" area, you can click the run button to start metric evaluation. You can start metric evaluation with and empty input domain and the result will be always zero.
[[Image:interface1|Defining an input domain]]
Let's first have a look at the buttons in the main toolbar, see the following figure in which the main toolbar is highlighted:
[[Image:interface2|Defining an input domain]]
[[Image:metrics-tool--debug-run-icon|Defining an input domain]] Start metric evaluation <br/>
Press this button to start evaluating the currently selected metric.
[[Image:metrics-tool--debug-stop-icon|Defining an input domain]] Stop metric<br/>
Press this button to terminate a running metric evaluation.
[[Image:metrics-tool--metric-send-to-archive-icon|Defining an input domain]] Send last result to metric history<br/>
After a metric evaluation this button will be sensitive and clicking it will record the evaluated metric as well as its input domain and result in the metric history. This facilitates evaluating it again and lets you compare different metric runs.
[[Image:metrics-tool--metric-run-and-show-details-icon|Defining an input domain]] Keep detailed result when evaluating metric<br/>
Normally, evaluating a metric will give you a number as result, but sometimes, you want to investigate into those items which make up that value. For example, evaluating '''Classes''' metric over the base library gives you 242, which means there are 242 classes in the base library, and sometimes, you want to know which they are. With this option enabled, you'll have a detailed result listed in the detailed result panel after a metric evaluation. This option only has effect when evaluating basic metrics, because the detailed result has no meaning for derived metrics (linear or ratio metrics) in general. Suppose you have a linear metric defined as 5 * Classes, then the notion of detailed result has no meaning. Another use of this option is for performance: keeping a detailed result can be quite expensive in some cases, such as when you calculate the metric '''Lines of code''' for a large system, which may result in hundred of thousands of lines in the result. So turning it off in such as case may be a good idea.
[[Image:metrics-tool--metric-filter-icon|Defining an input domain]] Filter result which is not visible from input domain<br/>
If this option is enabled, all non visible items from the input domain will be filtered. For definition of "non visible" items, please see documentation for criterion is_visible.
[[Image:metrics-tool--context-sync-icon|Defining an input domain]] Automatically go to result panel after metric evaluation<br/>
If this option is enabled, the metric tool will switch to the detailed result panel after a metric evaluation.
[[Image:metrics-tool--metric-quick-icon|Defining an input domain]] Define quick metric<br/>
Sometimes, you want to calculate some metrics which are not defined already. For example, find a feature which is named "foo". And it may be just a one time thing, so there is no need to go to metric definition panel, define and save a metric and then go back to evaluation panel and run it. Quick metric is designed for this situation, you can defined any basic metric in the quick metric definition area. It's the same as the basic metric definition area in the metric definition panel. Just define your metric and run it.
In the following figure, a defined quick metric is shown:
[[Image:interface3|Defining an input domain]]

80
documentation/17.01/eiffelstudio/eiffelstudio-reference/metrics-tool/user-interface-basics/metric-history-panel.wiki Normal file
View File

@@ -0,0 +1,80 @@
[[Property:title|Metric History Panel]]
[[Property:weight|3]]
[[Property:uuid|373d7403-eb3a-3c05-787e-b4a8cb5848cb]]
The metric history panel lists all recorded metric evaluations. You can select them and reevaluate them to see the new value and if it differs from the old result.
Lets have a look at the buttons in the main toolbar highlighted in the following figure:
[[Image:interface14|Metric history panel]]
[[Image:metrics-tool--debug-run-icon|Run history]] Recalculate history<br/>Recalculate selected metric history items
[[Image:metrics-tool--debug-stop-icon|Stop history]] Stop history recalculation<br/>Stop running metric history recalculation.
[[Image:metrics-tool--metric-run-and-show-details-icon|Keep detailed result]] Keep detailed metric result<br/>
If this option is enabled, the detailed metric result will be kept and will be available after a metric history recalculation.
[[Image:metrics-tool--metric-unit-assertion-icon|Check warning]] Check metric history warnings<br/>If this option is enabled, specified metric history warnings will be checked.
[[Image:metrics-tool--general-reset-icon|Remove detailed result]] Remove detailed metric result<br/>Remove detailed metric result, if any.
[[Image:metrics-tool--general-remove-icon|Remove history]] Remove metric history item<br/>Remove selected metric history items.
[[Image:metrics-tool--metric-group-icon|Show tree]] Display tree view<br/>If this option is enabled, the metric history items will be displayed in a tree view.
[[Image:interface16|Hide old metrics]] Hide old metric history<br/>Hide metric history items which are calculated before the specified number of days
[[Image:select-all|select all history]] Select All<br/>Select all recorded metric history items.
[[Image:deselect-all|deselect all history]] Deselect All<br/>Deselect all recorded metric history items.
[[Image:select-recalculatable|select all calculatable]] Select all recalculatable history items<br/>Select all recalculatable metric history items. A metric history item is recalculatable if its associated metric is valid and its specified input domain is valid.
[[Image:deselect-recalculatable|deselect all calculatable]] Deselect all recalculatable history items<br/>Deselect all recalculatable metric history items.
==Recalculate Metric History==
To recalculate a metric history, you need to selected those items that you want to recalculate. In the following figure, a metric history item '''Uncommented features''' is selected.
[[Image:interface17|Select metric history]]
After recalculating the selected metric history items, the result will be highlighted, as shown in the following figure:
[[Image:interface18|History recalculationg result]]
In the above figure, the row '''Uncommented features''' is highlighted indicating that this item has been recalculated. And from the row, we can see that the current value is 1 while the previous value is 0, meaning that there is one uncommented feature in cluster sample now while there was no uncommented feature in cluster sample when this metric was calculated the last time.
==Metric History Warning Checking==
Another thing you can do in metric history is to assign a warning tester to each item. When the metric history is recalculated with metric history warning checking enabled, the warning tester will be evaluated against the metric value to see if it's condition is satisfied.
Let's use an example to demonstrate the idea. Suppose we have set up a metric history warning shown in the following two figures:
[[Image:interface20|warning tester]]
[[Image:interface19|warning tester]]
This warning means, when the metric '''Uncommented features''' is calculated over the input domain {sample}, the value should be zero, otherwise a warning should be emitted.
After recalculating the metric history item, we get the following result:
[[Image:interface21|warning tester]]
From the above result, we can see that the value of the metric '''Uncommented features''' over the input domain {sample} is 1 while our warning says it should be 0. So we get a warning message.