|
@@ -60,9 +60,6 @@
|
|
|
<li class="">
|
|
|
<a href="./index.html">Home</a>
|
|
|
</li>
|
|
|
- <li class="">
|
|
|
- <a href="./customize.html"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=275605&type=10" alt="Get Software Index at SourceForge.net. Fast, secure and Free Open Source software downloads" border="0"></a>
|
|
|
- </li>
|
|
|
</ul>
|
|
|
</div>
|
|
|
</div>
|
|
@@ -425,7 +422,7 @@ file: __global__: comment
|
|
|
</section>
|
|
|
<section id="workflow_view_summary_section">
|
|
|
<h3>Summary metrics and distribution tables/graphs</h3>
|
|
|
- <p>It is time to look at the data. The command:</p>
|
|
|
+ <p>It is time to look at the data files collected (step above). The command:</p>
|
|
|
<pre>
|
|
|
> python "/path/to/metrix++.py" view --db-file=boost_1_54_0/metrixpp.db
|
|
|
</pre>
|
|
@@ -650,7 +647,7 @@ file: __global__: comment
|
|
|
in xml pr python disctionary formats. This can be particularly useful for integration of the tool with
|
|
|
other applications. For example, an editor may re-collect and show context based metrics when a file is saved.</p>
|
|
|
<pre>
|
|
|
-> python "/path/to/metrix++.py" view --format=xml
|
|
|
+> python "/path/to/metrix++.py" view --db-file=boost_1_54_0/metrixpp.db --format=xml
|
|
|
</pre>
|
|
|
<p>Check other options of the view tool by executing:</p>
|
|
|
<pre>
|
|
@@ -659,21 +656,281 @@ file: __global__: comment
|
|
|
</section>
|
|
|
<section id="workflow_limit_section">
|
|
|
<h2>Apply thresholds</h2>
|
|
|
- <p>...</p>
|
|
|
+ <p>The viewer shows (above) that there are function with quite large value of cyclomatic complexity metric.
|
|
|
+ Growth of this metric can be considered as negative trend. Metrix++ 'limit' tool offers the capability
|
|
|
+ to organise the control over trends by applying limits to metric values.
|
|
|
+ Exceeded limites are alarms in the quality management and control.</p>
|
|
|
</section>
|
|
|
<section id="workflow_limit_hotspots_section">
|
|
|
- <h3>Suppressions</h3>
|
|
|
- <p>Metrix++ has got suppressions capability. Suppressions are collected from comments in code
|
|
|
- and used by post-processing tools, like 'limit'. It allows to take fine grained control
|
|
|
- over false-positive warnings, if there are.</p>
|
|
|
+ <h3>Hotspots</h3>
|
|
|
+ <p>Hotspots mode of the limit tool helps to identify top files/regions exceeding a metric threshold.
|
|
|
+ Let's identify top 3 functions in boost interprocess library, which exceed limit of 15 points of
|
|
|
+ cyclomatic complexity metric:</p>
|
|
|
+ <pre>
|
|
|
+> python "/path/to/metrix++.py" limit --db-file=boost_1_54_0/metrixpp.db --max-limit=std.code.complexity:cyclomatic:15 --hotspots=3
|
|
|
+</pre>
|
|
|
+ <pre>
|
|
|
+./interprocess/detail/managed_open_or_create_impl.hpp:302: warning: Metric 'std.code.complexity:cyclomatic' for region 'priv_open_or_create' exceeds the limit.
|
|
|
+ Metric name : std.code.complexity:cyclomatic
|
|
|
+ Region name : priv_open_or_create
|
|
|
+ Metric value : 37
|
|
|
+ Modified : None
|
|
|
+ Change trend : None
|
|
|
+ Limit : 15.0
|
|
|
+ Suppressed : False
|
|
|
+
|
|
|
+./interprocess/streams/vectorstream.hpp:284: warning: Metric 'std.code.complexity:cyclomatic' for region 'seekoff' exceeds the limit.
|
|
|
+ Metric name : std.code.complexity:cyclomatic
|
|
|
+ Region name : seekoff
|
|
|
+ Metric value : 25
|
|
|
+ Modified : None
|
|
|
+ Change trend : None
|
|
|
+ Limit : 15.0
|
|
|
+ Suppressed : False
|
|
|
+
|
|
|
+./interprocess/streams/bufferstream.hpp:174: warning: Metric 'std.code.complexity:cyclomatic' for region 'seekoff' exceeds the limit.
|
|
|
+ Metric name : std.code.complexity:cyclomatic
|
|
|
+ Region name : seekoff
|
|
|
+ Metric value : 23
|
|
|
+ Modified : None
|
|
|
+ Change trend : None
|
|
|
+ Limit : 15.0
|
|
|
+ Suppressed : False
|
|
|
+</pre>
|
|
|
</section>
|
|
|
<section id="workflow_limit_control_section">
|
|
|
- <h3>Suppressions</h3>
|
|
|
- <p>Metrix++ has got suppressions capability. Suppressions are collected from comments in code
|
|
|
- and used by post-processing tools, like 'limit'. It allows to take fine grained control
|
|
|
- over false-positive warnings, if there are.</p>
|
|
|
+ <h3>Controlling trends</h3>
|
|
|
+ <p>Exit code of the 'limit' tool is equal to number of warnings printed. This allows to use the tool
|
|
|
+ as a static analysis tool during software build process. In this case, non-zero exit code means
|
|
|
+ that there are violations to the agreed standards and it may fail the build. So, the same command
|
|
|
+ without --hotspots option will print all regions/files exceeding the specified limit:</p>
|
|
|
+ <pre>
|
|
|
+> python "/path/to/metrix++.py" limit --db-file=boost_1_54_0/metrixpp.db --max-limit=std.code.complexity:cyclomatic:15
|
|
|
+</pre>
|
|
|
+ <h4>Modes to exclude old code from the considiration</h4>
|
|
|
+ <p>However, it is likely there are many warnings printed in this mode, especially if very old or legacy code is profiled
|
|
|
+ against new metrics and coding rules. Although all warnings can be removed
|
|
|
+ by re-factoring in scope of big task force activity, it is where many tools are rejected,
|
|
|
+ because it is difficult to justify the initial cost of applying and integrating them.
|
|
|
+ Metrix++ 'limit' tool has got an option --warn-mode, which helps to overcome this problem.</p>
|
|
|
+ <p>--warn-mode=touched encourages re-factoring only for new and modified regions. It enables
|
|
|
+ continuous refactoring. It does not matter how late the rule is applied or
|
|
|
+ coding standard is modified. It is possible to do it anytime with zero initial investment.
|
|
|
+ For example, applying it to boost interprocess library for a changes between 1.52 and 1.54 versions
|
|
|
+ results in only 6 warnings:</p>
|
|
|
+ <pre>
|
|
|
+> python "/path/to/metrix++.py" limit --db-file=boost_1_54_0/metrixpp.db --db-file-prev=boost_1_52_0/metrixpp.db --max-limit=std.code.complexity:cyclomatic:15 --warn-mode=touched
|
|
|
+</pre>
|
|
|
+ <pre>
|
|
|
+./interprocess/detail/managed_open_or_create_impl.hpp:302: warning: Metric 'std.code.complexity:cyclomatic' for region 'priv_open_or_create' exceeds the limit.
|
|
|
+ Metric name : std.code.complexity:cyclomatic
|
|
|
+ Region name : priv_open_or_create
|
|
|
+ Metric value : 37
|
|
|
+ Modified : True
|
|
|
+ Change trend : +1
|
|
|
+ Limit : 15.0
|
|
|
+ Suppressed : False
|
|
|
+
|
|
|
+./interprocess/ipc/message_queue.hpp:375: warning: Metric 'std.code.complexity:cyclomatic' for region 'insert_at' exceeds the limit.
|
|
|
+ Metric name : std.code.complexity:cyclomatic
|
|
|
+ Region name : insert_at
|
|
|
+ Metric value : 16
|
|
|
+ Modified : True
|
|
|
+ Change trend : 0
|
|
|
+ Limit : 15.0
|
|
|
+ Suppressed : False
|
|
|
+
|
|
|
+./interprocess/mapped_region.hpp:575: warning: Metric 'std.code.complexity:cyclomatic' for region 'mapped_region' exceeds the limit.
|
|
|
+ Metric name : std.code.complexity:cyclomatic
|
|
|
+ Region name : mapped_region
|
|
|
+ Metric value : 18
|
|
|
+ Modified : True
|
|
|
+ Change trend : +2
|
|
|
+ Limit : 15.0
|
|
|
+ Suppressed : False
|
|
|
+
|
|
|
+./interprocess/mem_algo/detail/mem_algo_common.hpp:452: warning: Metric 'std.code.complexity:cyclomatic' for region 'priv_allocate_many' exceeds the limit.
|
|
|
+ Metric name : std.code.complexity:cyclomatic
|
|
|
+ Region name : priv_allocate_many
|
|
|
+ Metric value : 20
|
|
|
+ Modified : True
|
|
|
+ Change trend : 0
|
|
|
+ Limit : 15.0
|
|
|
+ Suppressed : False
|
|
|
+
|
|
|
+./interprocess/mem_algo/rbtree_best_fit.hpp:787: warning: Metric 'std.code.complexity:cyclomatic' for region 'priv_expand_both_sides' exceeds the limit.
|
|
|
+ Metric name : std.code.complexity:cyclomatic
|
|
|
+ Region name : priv_expand_both_sides
|
|
|
+ Metric value : 17
|
|
|
+ Modified : True
|
|
|
+ Change trend : 0
|
|
|
+ Limit : 15.0
|
|
|
+ Suppressed : False
|
|
|
+
|
|
|
+./interprocess/sync/windows/named_sync.hpp:98: warning: Metric 'std.code.complexity:cyclomatic' for region 'open_or_create' exceeds the limit.
|
|
|
+ Metric name : std.code.complexity:cyclomatic
|
|
|
+ Region name : open_or_create
|
|
|
+ Metric value : 18
|
|
|
+ Modified : True
|
|
|
+ Change trend : 0
|
|
|
+ Limit : 15.0
|
|
|
+ Suppressed : False
|
|
|
+</pre>
|
|
|
+ <p>If it is challenging or not beneficial to refactor everything touched,
|
|
|
+ --warn-mode=trends simplifies the control over modified regions and only makes sure
|
|
|
+ that there are no regressions in modified code. In other words, a warning is printed about modified region/file
|
|
|
+ only if a metric exceeds the specified limit and the value of the metric has got negative trend in modification.
|
|
|
+ It is possible to apply it anytime with zero initial investment and almost zero on-going investment around old code.
|
|
|
+ For example, applying it to boost interprocess library for a changes between 1.52 and 1.54 versions
|
|
|
+ results in only 2 warnings:</p>
|
|
|
+ <pre>
|
|
|
+> python "/path/to/metrix++.py" limit --db-file=boost_1_54_0/metrixpp.db --db-file-prev=boost_1_52_0/metrixpp.db --max-limit=std.code.complexity:cyclomatic:15 --warn-mode=trend
|
|
|
+</pre>
|
|
|
+ <pre>
|
|
|
+./interprocess/detail/managed_open_or_create_impl.hpp:302: warning: Metric 'std.code.complexity:cyclomatic' for region 'priv_open_or_create' exceeds the limit.
|
|
|
+ Metric name : std.code.complexity:cyclomatic
|
|
|
+ Region name : priv_open_or_create
|
|
|
+ Metric value : 37
|
|
|
+ Modified : True
|
|
|
+ Change trend : +1
|
|
|
+ Limit : 15.0
|
|
|
+ Suppressed : False
|
|
|
+
|
|
|
+./interprocess/mapped_region.hpp:575: warning: Metric 'std.code.complexity:cyclomatic' for region 'mapped_region' exceeds the limit.
|
|
|
+ Metric name : std.code.complexity:cyclomatic
|
|
|
+ Region name : mapped_region
|
|
|
+ Metric value : 18
|
|
|
+ Modified : True
|
|
|
+ Change trend : +2
|
|
|
+ Limit : 15.0
|
|
|
+ Suppressed : False
|
|
|
+</pre>
|
|
|
+ <p>--warn-mode=new drops control over existing code and ensures that warnings are only about new code.
|
|
|
+ For example, applying it to boost interprocess library for a changes between 1.52 and 1.54 versions
|
|
|
+ results in 0 warnings, so new code is totally compliant with the standard required in the example.</p>
|
|
|
+ <pre>
|
|
|
+> python "/path/to/metrix++.py" limit --db-file=boost_1_54_0/metrixpp.db --db-file-prev=boost_1_52_0/metrixpp.db --max-limit=std.code.complexity:cyclomatic:15 --warn-mode=new
|
|
|
+</pre>
|
|
|
+ <h4>Suppressions</h4>
|
|
|
+ <p>It is possible to suppress warnings on exceptional basis. Suppressions are collected from comments in code
|
|
|
+ and used by the 'limit' tool to filter out unnecessary (suppressed) warnings.
|
|
|
+ It allows to take fine grained control over false-positive warnings, if there are.</p>
|
|
|
+ <p>In order to suppress a warning:</p>
|
|
|
+ <ul>
|
|
|
+ <li>per region metrics: put the metrix++ instruction in the comments before the region, for example:</li>
|
|
|
+ <pre class="prettyprint linenums">
|
|
|
+// This function returns string typed
|
|
|
+// representation of a name of a color,
|
|
|
+// requested by color's id
|
|
|
+// metrix++: suppress std.code.complexity:cyclomatic
|
|
|
+std::string getColorName(int color_id)
|
|
|
+{
|
|
|
+ switch (color_id)
|
|
|
+ {
|
|
|
+ case COLOR_RED:
|
|
|
+ return std::string("red")
|
|
|
+ case COLOR_GREEN:
|
|
|
+ return std::string("green")
|
|
|
+ case COLOR_BLUE:
|
|
|
+ return std::string("blue")
|
|
|
+ /* and so on */
|
|
|
+ }
|
|
|
+}
|
|
|
+</pre>
|
|
|
+ <li>per file metrics: put the metrix++ instruction in the comments at the beginning of a file, for example:</li>
|
|
|
+ <pre class="prettyprint linenums">
|
|
|
+//
|
|
|
+// This file does processing of colors and brushes
|
|
|
+// Copyright is my company, 2013
|
|
|
+//
|
|
|
+// However, it is too long and big file, and there is no time
|
|
|
+// to split it into multiple file, so shut up the metrix++ warnings:
|
|
|
+// metrix++: suppress std.general:size
|
|
|
+//
|
|
|
+
|
|
|
+std::string getColorName(int color_id)
|
|
|
+{
|
|
|
+ ...
|
|
|
+...
|
|
|
+</pre>
|
|
|
+ <li>activate collection of suppressions:</li>
|
|
|
+ <pre>
|
|
|
+> python "/path/to/metrix++.py" collect --std.suppress
|
|
|
+</pre>
|
|
|
+ <li>run the 'limit' tool WITHOUT --disable-suppressions option:</li>
|
|
|
+ <pre>
|
|
|
+> python "/path/to/metrix++.py" limit ...
|
|
|
+</pre>
|
|
|
+ </ul>
|
|
|
+ <h5>Important notice:</h5>
|
|
|
+ <ul><li>--std.suppress option enables collection of 2 metrics as well: 'std.suppress:count' and
|
|
|
+ 'std.suppress.file:count'. The first is number of suppressions per region.
|
|
|
+ The second is the same but applies to file-scope metrics.
|
|
|
+ It allows to manage the amount of suppressions.
|
|
|
+ Usually there are no false-positives to suppress with the <strong>right</strong> metric,
|
|
|
+ but could be exceptions in specific cases. Managing suppressions is about managing exceptions.
|
|
|
+ If there are many exceptional cases, maybe something is wrong with a metric or an application of a metric.
|
|
|
+ Two code examples about colors above do not demonstrate the technically exceptional case,
|
|
|
+ they likely demonstrate a case of a process exception, like "there is no time to do it proper now", or
|
|
|
+ a case of wrong application of a metric, like "shut up the useless tool". So, be careful.
|
|
|
+ The 'view' tool shows number of suppressions and its change trends on per metric basis.</li></ul>
|
|
|
</section>
|
|
|
|
|
|
+ <section id="workflow_other_section">
|
|
|
+ <h2>Other applications</h2>
|
|
|
+ <h3>Checking data file properties</h3>
|
|
|
+ <p>Metrix++ 'info' tool is helpful to check properties of a data file, like settings used to write it,
|
|
|
+ colected metrics and files processed. For example:</p>
|
|
|
+ <pre>
|
|
|
+> python "/path/to/metrix++.py" info --db-file=boost_1_54_0/metrixpp.db
|
|
|
+</pre>
|
|
|
+ <pre>
|
|
|
+boost_1_54_0/metrixpp.db:: info: Created using plugins and settings:
|
|
|
+ version : 1.0
|
|
|
+ std.code.complexity:version: 1.1
|
|
|
+ std.code.cpp:version: 1.1
|
|
|
+ std.code.cpp:files: *.c,*.cc,*.cpp,*.cxx,*.h,*.hh,*.hpp,*.hxx
|
|
|
+ std.code.cs:version: 1.0
|
|
|
+ std.code.cs:files: *.cs
|
|
|
+ std.code.java:version: 1.1
|
|
|
+ std.code.java:files: *.java
|
|
|
+ std.code.lines:version: 1.1
|
|
|
+
|
|
|
+test_workflow.db:: info: Collected metrics:
|
|
|
+ std.code.complexity:cyclomatic:
|
|
|
+ std.code.lines:code:
|
|
|
+
|
|
|
+:: info: Processed files and checksums:
|
|
|
+ ./interprocess/allocators/detail/node_pool.hpp: 0xb099a7c3
|
|
|
+ ./interprocess/allocators/detail/node_tools.hpp: 0xaaf5044d
|
|
|
+ ./interprocess/anonymous_shared_memory.hpp: 0x2bf06cb0
|
|
|
+ ./interprocess/containers/allocation_type.hpp: 0x8e95cda0
|
|
|
+ ./interprocess/containers/containers_fwd.hpp: 0xa4d0d9f7
|
|
|
+ ./interprocess/containers/deque.hpp: 0x6dbb77af
|
|
|
+ ./interprocess/containers/flat_map.hpp: 0x6750338c
|
|
|
+ ...
|
|
|
+</pre>
|
|
|
+ <h3>Exporting results</h3>
|
|
|
+ <p>Metrix++ 'export' tool exports data files to csv formated files. For example:</p>
|
|
|
+ <pre>
|
|
|
+> python "/path/to/metrix++.py" export --db-file=boost_1_54_0/metrixpp.db > boost_1_54_0/metrixpp.csv
|
|
|
+</pre>
|
|
|
+ <pre>
|
|
|
+file,region,type,modified,line start,line end,std.code.complexity:cyclomatic,std.code.lines:code
|
|
|
+./interprocess/allocators/detail/node_pool.hpp,__global__,global,,1,110,,0
|
|
|
+./interprocess/allocators/detail/node_pool.hpp,boost,namespace,,33,105,,2
|
|
|
+./interprocess/allocators/detail/node_pool.hpp,interprocess,namespace,,34,104,,2
|
|
|
+./interprocess/allocators/detail/node_pool.hpp,ipcdetail,namespace,,35,103,,4
|
|
|
+./interprocess/allocators/detail/node_pool.hpp,SegmentManager,class,,39,72,,16
|
|
|
+...
|
|
|
+</pre>
|
|
|
+ <p>Files with csv format can be opened by applications, like Microsoft Office Excel, with advanced analysis capabilities.
|
|
|
+ For example, to draw this distribution graph:</p>
|
|
|
+ <p align="center"><img src="assets/img/piechart.png"/></p>
|
|
|
+ <p>It is not recommended to use export tool to implement custom post-analysis Metrix++ extensions.
|
|
|
+ The main reason is non granted backward compatibility support for csv columns. Another main reason is that
|
|
|
+ exporting is relatively slow process. It is recommended to use Metrix++ extensions API instead.</p>
|
|
|
+ </section>
|
|
|
<section id="extend_section">
|
|
|
<div class="page-header">
|
|
|
<h1>Create plugin</h1>
|
|
@@ -703,17 +960,31 @@ file: __global__: comment
|
|
|
================================================== -->
|
|
|
<footer class="footer">
|
|
|
<div class="container">
|
|
|
- <p>Copyright <strong>©</strong> 2009 - 2013, <a href="mailto:avkonst@users.sourceforge.net"><span class="normalImportance">Metrix++</span> Project</a></p>
|
|
|
- <p>Code licensed under <a href="http://www.gnu.org/licenses/gpl.txt" target="_blank">GPL 3.0</a>, documentation under <a href="http://creativecommons.org/licenses/by/3.0/">CC BY 3.0</a>.</p>
|
|
|
- <ul class="footer-links">
|
|
|
- <li><a href="#">Report defect</a></li>
|
|
|
- <li class="muted">·</li>
|
|
|
- <li><a href="#">Feature request</a></li>
|
|
|
- <li class="muted">·</li>
|
|
|
- <li><a href="#">Known issues</a></li>
|
|
|
- <li class="muted">·</li>
|
|
|
- <li><a href="#">Changelog</a></li>
|
|
|
- </ul>
|
|
|
+ <div class="row">
|
|
|
+ <div class="span3">
|
|
|
+ <p><a href="http://sourceforge.net/projects/metrixplusplus/"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=275605&type=3"
|
|
|
+ alt="Get Metrix++ at SourceForge.net. Fast, secure and Free Open Source software downloads" border="0"></a></p>
|
|
|
+ <p>·</p>
|
|
|
+ <p>· ·<script type="text/javascript" src="http://www.ohloh.net/p/485947/widgets/project_users_logo.js"></script></p>
|
|
|
+ <p><a href="http://freecode.com/projects/metrix"><img src="assets/img/fm_logo.png" width="130"></a></p>
|
|
|
+ <p>·</p>
|
|
|
+ </div>
|
|
|
+ <div class="span9">
|
|
|
+ <p>Copyright <strong>©</strong> 2009 - 2013, <a href="mailto:avkonst@users.sourceforge.net"><span class="normalImportance">Metrix++</span> Project</a></p>
|
|
|
+ <p>Code licensed under <a href="http://www.gnu.org/licenses/gpl.txt" target="_blank">GPL 3.0</a>, documentation under <a href="http://creativecommons.org/licenses/by/3.0/">CC BY 3.0</a>.</p>
|
|
|
+ <ul class="footer-links">
|
|
|
+ <li><a href="https://sourceforge.net/p/metrixplusplus/tickets/new/">Ask question</a></li>
|
|
|
+ <li class="muted">·</li>
|
|
|
+ <li><a href="https://sourceforge.net/p/metrixplusplus/tickets/new/">Report defect</a></li>
|
|
|
+ <li class="muted">·</li>
|
|
|
+ <li><a href="https://sourceforge.net/p/metrixplusplus/tickets/new/">Feature request</a></li>
|
|
|
+ <li class="muted">·</li>
|
|
|
+ <li><a href="https://sourceforge.net/p/metrixplusplus/tickets/search/?q=%21status%3Awont-fix+%26%26+%21status%3Aclosed">Open issues</a></li>
|
|
|
+ <li class="muted">·</li>
|
|
|
+ <li><a href="https://sourceforge.net/p/metrixplusplus/wiki/ChangeLog/">Changelog</a></li>
|
|
|
+ </ul>
|
|
|
+ </div>
|
|
|
+ </div>
|
|
|
</div>
|
|
|
</footer>
|
|
|
|