Skip to content

Commit a7563ec

Browse files
matsoftwarematsoftware
committed
Moved documentation code from readme to guide page
1 parent b0498a6 commit a7563ec

File tree

2 files changed

+124
-115
lines changed

2 files changed

+124
-115
lines changed

‎README.md‎

Lines changed: 3 additions & 115 deletions
Original file line numberDiff line numberDiff line change
@@ -35,121 +35,9 @@ The syntax is:
3535
- `--tests-paths` (default: `Test Tests`) space separated list of path substrings matching test classes
3636
- `--generate-graphs` (optional) if passed, it will generate the graphs related to the analysis and save them in the artifacts folder
3737

38-
### Output format
39-
40-
The `output.json` file will contain the metrics related to all frameworks
41-
and an _aggregate_ result for the project.
42-
43-
The example below is available [here](tests/test_resources/expected_output.json).
44-
45-
```json
46-
{
47-
"non-test-frameworks": [
48-
{
49-
"BusinessLogic": {
50-
"loc": 49,
51-
"noc": 7,
52-
"poc": 12.5,
53-
"n_a": 0,
54-
"n_c": 3,
55-
"nbm": 3,
56-
"analysis": "The code is under commented. Low abstract component, few interfaces. ",
57-
"not": 0,
58-
"fan_in": 1,
59-
"fan_out": 2,
60-
"i": 0.667,
61-
"a": 0.0,
62-
"d_3": 0.333
63-
}
64-
},
65-
66-
...
67-
68-
],
69-
"tests-frameworks": [
70-
{
71-
"BusinessLogic_Test": {
72-
"loc": 7,
73-
"noc": 7,
74-
"poc": 50.0,
75-
"n_a": 0,
76-
"n_c": 1,
77-
"nbm": 1,
78-
"analysis": "The code is over commented. ",
79-
"not": 1
80-
}
81-
},
82-
83-
...
84-
85-
86-
],
87-
"aggregate": {
88-
"non-test-frameworks": {
89-
"loc": 97,
90-
"noc": 35,
91-
"n_a": 1,
92-
"n_c": 7,
93-
"nbm": 10,
94-
"not": 0,
95-
"poc": 26.515
96-
},
97-
"tests-frameworks": {
98-
"loc": 53,
99-
"noc": 28,
100-
"n_a": 0,
101-
"n_c": 4,
102-
"nbm": 7,
103-
"not": 5,
104-
"poc": 34.568
105-
},
106-
"total": {
107-
"loc": 150,
108-
"noc": 63,
109-
"n_a": 1,
110-
"n_c": 11,
111-
"nbm": 17,
112-
"not": 5,
113-
"poc": 29.577
114-
}
115-
}
116-
}
117-
```
118-
119-
Legend:
120-
121-
| Key | Metric | Description |
122-
|:---------:|:--------------------------------:|:---------------------------------------------------------------------------------------------------:|
123-
| `loc` | Lines Of Code | Number of lines of code (empty lines excluded) |
124-
| `noc` | Number of Comments | Number of comments |
125-
| `poc` | Percentage of Comments | 100 * noc / ( noc + loc) |
126-
| `fan_in` | Fan-In | Incoming dependencies: number of classes outside the framework that depend on classes inside it. |
127-
| `fan_out` | Fan-Out | Outgoing dependencies: number of classes inside this component that depend on classes outside it. |
128-
| `i` | Instability | I = fan_out / (fan_in + fan_out) |
129-
| `n_a` | Number of abstracts | Number of protocols in the framework |
130-
| `n_c` | Number of concretes | Number of struct and classes in the framework |
131-
| `a` | Abstractness | A = n_a / n_c |
132-
| `d_3` | Distance from the main sequence | D³ = abs( A + I - 1 ) |
133-
| `nbm` | Number of methods | Number of `func` (computed `var` excluded) |
134-
| `not` | Number of tests | Number of methods in test frameworks starting with `test` |
135-
136-
## Example
137-
138-
A sample project is provided in the `resources` folder:
139-
140-
`python3 swift-code-metrics-runner.py --source tests/test_resources/ExampleProject/SwiftCodeMetricsExample --artifacts report --generate-graphs`
141-
142-
The graphs that will be generated are the following:
143-
144-
| Code distribution |
145-
|:-----------:|
146-
|![LOC](docs/assets/lines_of_code_-_loc.jpg) ![NOC](docs/assets/number_of_comments_-_noc.jpg) ![Nc](docs/assets/n._of_classes_and_structs.jpg) ![Nbm](docs/assets/n._of_methods_-_nbm.jpg) ![NOT](docs/assets/number_of_tests_-_not.jpg) ![Abstractness](docs/assets/abstractness_-_a.jpg) ![Instability](docs/assets/instability_-_i.jpg) ![Code distribution](docs/assets/code_distribution.jpg) |
147-
148-
| Component coupling |
149-
|:-----------:|
150-
| ![Distance from main sequence](docs/assets/deviation_from_the_main_sequence.jpg)
151-
| ![Dependency graph](docs/assets/dependency_graph.jpg)
152-
| Dependency graph
38+
## Documentation
39+
40+
Please follow the [guide](docs/GUIDE.md) with a practical example to get started.
15341

15442
## Current limitations
15543

‎docs/GUIDE.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
## Guide
2+
3+
How to use `swift-code-metrics`.
4+
5+
## Example project
6+
7+
A sample project is provided in the `resources` folder:
8+
9+
`python3 swift-code-metrics-runner.py --source tests/test_resources/ExampleProject/SwiftCodeMetricsExample --artifacts report --generate-graphs`
10+
11+
### Output format
12+
13+
The `output.json` file will contain the metrics related to all frameworks
14+
and an _aggregate_ result for the project.
15+
16+
The example below is available [here](../tests/test_resources/expected_output.json).
17+
18+
```json
19+
{
20+
"non-test-frameworks": [
21+
{
22+
"BusinessLogic": {
23+
"loc": 49,
24+
"noc": 7,
25+
"poc": 12.5,
26+
"n_a": 0,
27+
"n_c": 3,
28+
"nbm": 3,
29+
"analysis": "The code is under commented. Low abstract component, few interfaces. ",
30+
"not": 0,
31+
"fan_in": 1,
32+
"fan_out": 2,
33+
"i": 0.667,
34+
"a": 0.0,
35+
"d_3": 0.333
36+
}
37+
},
38+
39+
...
40+
41+
],
42+
"tests-frameworks": [
43+
{
44+
"BusinessLogic_Test": {
45+
"loc": 7,
46+
"noc": 7,
47+
"poc": 50.0,
48+
"n_a": 0,
49+
"n_c": 1,
50+
"nbm": 1,
51+
"analysis": "The code is over commented. ",
52+
"not": 1
53+
}
54+
},
55+
56+
...
57+
58+
59+
],
60+
"aggregate": {
61+
"non-test-frameworks": {
62+
"loc": 97,
63+
"noc": 35,
64+
"n_a": 1,
65+
"n_c": 7,
66+
"nbm": 10,
67+
"not": 0,
68+
"poc": 26.515
69+
},
70+
"tests-frameworks": {
71+
"loc": 53,
72+
"noc": 28,
73+
"n_a": 0,
74+
"n_c": 4,
75+
"nbm": 7,
76+
"not": 5,
77+
"poc": 34.568
78+
},
79+
"total": {
80+
"loc": 150,
81+
"noc": 63,
82+
"n_a": 1,
83+
"n_c": 11,
84+
"nbm": 17,
85+
"not": 5,
86+
"poc": 29.577
87+
}
88+
}
89+
}
90+
```
91+
92+
Legend:
93+
94+
| Key | Metric | Description |
95+
|:---------:|:--------------------------------:|:---------------------------------------------------------------------------------------------------:|
96+
| `loc` | Lines Of Code | Number of lines of code (empty lines excluded) |
97+
| `noc` | Number of Comments | Number of comments |
98+
| `poc` | Percentage of Comments | 100 * noc / ( noc + loc) |
99+
| `fan_in` | Fan-In | Incoming dependencies: number of classes outside the framework that depend on classes inside it. |
100+
| `fan_out` | Fan-Out | Outgoing dependencies: number of classes inside this component that depend on classes outside it. |
101+
| `i` | Instability | I = fan_out / (fan_in + fan_out) |
102+
| `n_a` | Number of abstracts | Number of protocols in the framework |
103+
| `n_c` | Number of concretes | Number of struct and classes in the framework |
104+
| `a` | Abstractness | A = n_a / n_c |
105+
| `d_3` | Distance from the main sequence | D³ = abs( A + I - 1 ) |
106+
| `nbm` | Number of methods | Number of `func` (computed `var` excluded) |
107+
| `not` | Number of tests | Number of methods in test frameworks starting with `test` |
108+
109+
## Graphs
110+
111+
The `--generate-graphs` option will output the following reports:
112+
113+
| Code distribution |
114+
|:-----------:|
115+
|![LOC](assets/lines_of_code_-_loc.jpg) ![NOC](assets/number_of_comments_-_noc.jpg) ![Nc](assets/n._of_classes_and_structs.jpg) ![Nbm](assets/n._of_methods_-_nbm.jpg) ![NOT](assets/number_of_tests_-_not.jpg) ![Abstractness](assets/abstractness_-_a.jpg) ![Instability](assets/instability_-_i.jpg) ![Code distribution](assets/code_distribution.jpg) |
116+
117+
| Component coupling |
118+
|:-----------:|
119+
| ![Distance from main sequence](assets/deviation_from_the_main_sequence.jpg) |
120+
| ![Dependency graph](assets/dependency_graph.jpg) |
121+
| Dependency graph |

0 commit comments

Comments
 (0)