[doc] Metrics documentation #517
Conversation
| to extend the framework with their own custom metrics." | ||
| last_updated: July 20, 2017 | ||
| sidebar: pmd_sidebar | ||
| permalink: pmd_devdocs_metrics_howto.html |
There was a problem hiding this comment.
I've meanwhile changed my naming convention: since we have "pmd" and "devdocs" already in the path as folder, I decided to do not repeat these in the filename. So, please rename this file to just metrics_howto.md.
Important: Keep the "permalink" as it is - this will be the final name of the html file, that is generated. Since this jekyll theme generates all pages flat in the root directory, it's easier to see then where this page belongs to (and avoid any clashes).
There was a problem hiding this comment.
I'm wondering, whether we really need this flat structure or whether we could reuse the folder structure? One argument was, that it's easier, if you link between the pages or include images, etc. You do not need to care about relative paths... But maybe, it would be better to have urls like https://pmd.github.io/pmd/devdocs/metrics_howto.html instead of https://pmd.github.io/pmd/pmd_devdocs_metrics_howto.html?
There was a problem hiding this comment.
Okay I'll rename it.
I think it would be nice to have a proper path in urls, it's more structured and overall cleaner. I fiddled a bit with jekyll but found no way to do that... The documentation theme's doc seems to hint that this is not possible:
The listing of all pages in the root directory (which happens when you add a permalink property to the pages) is what allows the relative linking and offline viewing of the site to work.
Besides the sidebar seems to remove any forward slash it finds in urls, so we cannot even specify urls manually. I guess the theme doesn't give us the choice
|
|
||
| ### Versions | ||
|
|
||
| * Version `CycloVersion#IGNORE_BOOLEAN_PATHS`: Boolean operators are not counted, nor are empty |
There was a problem hiding this comment.
Can we give here a reason, why we have this variant? Was it because of backwards-compatibility?
There was a problem hiding this comment.
Right this can be more detailed. It was to provide results similar to what the old StdCyclomaticComplexity provided, but as the rule will be removed I guess it's not even for backwards compatibility
| variables declared on the same line (e.g. `int a, b, c;`) as a single statement. | ||
| * Contrary to Sonarqube, but as JavaNCSS, we count type declarations (class, interface, enum, annotation), | ||
| and method and field declarations \[[Sonarqube](#Sonarqube)\]. | ||
| * Contrary to JavaNCSS, but as Sonarqube, we do not count package declaration and import declarations as statements. |
There was a problem hiding this comment.
I like to have the reasoning behind this... If I remember correctly, ignoring package/import declarations makes it easier, to compare two classes and compare a inner class with a top-level class, right?
There was a problem hiding this comment.
Right, at least in theory. Using this definition, the Ncss count of a class is only the statements that are inside the declaration (plus the declaration statement), which I think makes extra sense since import statements are more metadata for the compiler than code. Plus, most IDEs fold them by default so they don't hamper readability nearly as much as eg many field declarations
|
I'll merge this, although we'll probably change the location/structure, where we place the list of available metrics. We were discussing somewhere under language specific documentation, if I remember correctly. We should probably move then the rule documentation (see #526) also under the language specific section. |
A starting point for the documentation of metrics