Add documentation in Metrics.md

MathieuBuisson · May 12, 2017 · eeb3e80 · eeb3e80
1 parent e0a83a2
commit eeb3e80
Showing 1 changed file with 91 additions and 3 deletions.
diff --git a/docs/Metrics.md b/docs/Metrics.md
@@ -6,7 +6,7 @@
 It measures the number of lines of code in the specified function definition.  
 The single line comments, multiple lines comments and comment-based help are not executable code, so they are not counted.  
 
-This metric should be kept as low as possible because lenghty functions tend to be difficult to read and maintain.  
+Lower is better, because lenghty functions tend to be difficult to read and maintain.  
 
 #### Default thresholds : ([Source](http://www.ndepend.com/docs/code-metrics#NbLinesOfCode))  
   - Warning : greater or equal to 20  
@@ -19,7 +19,7 @@ It counts the total number of best practice violations found by [PSScriptAnalyze
 
 PSCodeHealth uses the default PSScriptAnalyzer rules.  
 
-This metric should be kept as low as possible because high numbers of PSScriptAnlyzer findings generally reflects low code quality, maintainability or safety.  
+Lower is better, because high numbers of PSScriptAnlyzer findings generally reflects low code quality, maintainability or safety.  
 
 #### Default thresholds :  
   - Warning : greater or equal to 7  
@@ -35,14 +35,21 @@ At the very least, it should have a short statement describing the function's pu
 It measures the percentage of lines of code in the specified function definition that are exercised (executed) during a suite of tests.  
 Note : the code **executed** during tests cannot always be considered as **tested**. It is only **tested** if it is executed **and** there is one or more test(s) specifically designed to validate that the code behaves as expected.  
 
-Good tests provide confidence that the code behaves as expected. How confident depends mostly on the percentage of code which is covered by the tests. This is why code coverage of the tests is an important metric. It is an indicator of how thoroughly the different possible code paths and edge cases are tested.  
+Higher is better. Good tests provide confidence that the code behaves as expected. How confident depends mostly on the percentage of code which is covered by the tests. This is why code coverage of the tests is an important metric. It is an indicator of how thoroughly the different possible code paths and edge cases are tested.  
 
 #### Default thresholds : ([Source](https://github.com/PowerShell/DscResources/blob/master/HighQualityModuleGuidelines.md))  
   - Warning : less than 80  
   - Fail : less than 70  
 
 ### Complexity  
+This is the cyclomatic complexity of a given function. Cyclomatic complexity measures the number of possible execution paths through a given section of code. This is intended to evaluation code complexity.  
 
+Lower is better, because complex code tends to have the following properties :  
+  - Difficult to read/understand  
+  - Difficult to test  
+  - More prone to defects  
+  - Make defects more difficult to identify
+  - More difficult and risky to change/refactor/maintain  
 
 #### Default thresholds : ([Source](http://www.ndepend.com/docs/code-metrics#CC))  
   - Warning : greater or equal to 15  
@@ -51,10 +58,91 @@ Good tests provide confidence that the code behaves as expected. How confident d
 For more details on how the cyclomatic complexity is calculated, please refer to [this article](http://theshellnut.com/measuring-powershell-code-complexity-why-and-how/).
 
 ### MaximumNestingDepth  
+This is the depth of the most deeply nested code in a given piece of code (a function, here). This measures a different aspect of complexity from the "cyclomatic complexity", so these 2 metrics are complementary. The nesting depth of a piece of code can measure the complexity of its context.  
 
+Again, lower is better.  
 
 #### Default thresholds : ([Source](http://www.ndepend.com/docs/code-metrics#ILNestingDepth))  
   - Warning : greater or equal to 4  
   - Fail : greater or equal to 8  
 
 For more details on how the maximum nesting depth is calculated, please refer to [this article](http://theshellnut.com/measuring-powershell-code-complexity-why-and-how/).
+
+## Metrics collected for the overall health report  
+
+These are the overall metrics for all PowerShell code in the files or folder specified via the **Path** parameter.
+
+### Files  
+The number of PowerShell files. These are files with an extension like : '\*.ps\*1'.  
+Test scripts are excluded, as are '\*.ps1xml' files because these don't contain any code.  
+
+### Functions  
+The overall number of function definitions found.  
+
+### LinesOfCodeTotal  
+The total number of lines of code across all files and functions.  
+
+#### Default thresholds :  
+  - Warning : greater or equal to 1000  
+  - Fail : greater or equal to 2000  
+
+### LinesOfCodeAverage  
+The average number of lines of code per function.  
+
+#### Default thresholds : ([Source](http://www.ndepend.com/docs/code-metrics#NbLinesOfCode))  
+  - Warning : greater or equal to 20  
+  - Fail : greater or equal to 40  
+
+### ScriptAnalyzerFindingsTotal  
+The total number of best practice violations found by [PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer) across all files.  
+
+#### Default thresholds :  
+  - Warning : greater or equal to 30  
+  - Fail : greater or equal to 60  
+
+### ScriptAnalyzerErrors  
+The total number of best practice violations of 'Error' severity found by [PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer) across all files.  
+
+#### Default thresholds :  
+  - Warning : greater or equal to 1  
+  - Fail : greater or equal to 3  
+
+### ScriptAnalyzerWarnings  
+The total number of best practice violations of 'Warning' severity found by [PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer) across all files. 
+
+#### Default thresholds :  
+  - Warning : greater or equal to 10  
+  - Fail : greater or equal to 20  
+
+### ScriptAnalyzerInformation  
+The total number of best practice violations of 'Information' severity found by [PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer) across all files.  
+
+#### Default thresholds :  
+  - Warning : greater or equal to 20  
+  - Fail : greater or equal to 40  
+
+### ScriptAnalyzerFindingsAverage  
+The average number of best practice violations found by [PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer) per function.
+
+### NumberOfTests  
+The total number of tests found by Pester.
+
+### NumberOfFailedTests  
+The total number of failed tests.  
+Lower is better, 0 is highly recommended.  
+
+### NumberOfPassedTests  
+The total number of failed tests.  
+
+### TestsPassRate  
+The overall percentage of passing tests.  
+The higher the better.  
+
+### TestCoverage  
+The overall percentage of code which is exercised across all PowerShell files by the tests.  
+The higher the better.  
+
+'CommandsMissedTotal'           
+'ComplexityAverage'             
+'NestingDepthAverage'           
+'FunctionHealthRecords'