You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+49-48Lines changed: 49 additions & 48 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,63 +1,67 @@
1
1
# RefactorFirst
2
2
3
3
This tool for Java codebases will help you identify what you should refactor first:
4
-
- God Classes
5
-
- Highly Coupled classes
6
-
- Class Cycles (with cycle images!)
4
+
- Class and Package Cycles (with cycle images!)
5
+
- Object Oriented Disharmonies (a.k.a anti-patterns) identified in [Object Oriented Metrics in Practice](https://link.springer.com/book/10.1007/3-540-39538-5)
7
6
8
-
It scans your Git repository generates a single page application by runing:
7
+
It scans your Git repository and generates a single page application by running:
9
8
- Cycle analysis on your source code using the [OpenRewrite](https://github.com/openrewrite/rewrite) Java parser and [JGraphT](https://jgrapht.org/)
10
9
- What-if analysis to identify the most optimal relationships in a class cycle to remove
11
-
- PMD's God Class Rule
12
-
- PMD's Coupling Between Objects
13
10
14
-
Code map viewers are powered by [3D Force Graph](https://vasturiano.github.io/3d-force-graph), [sigma.js](https://www.sigmajs.org/), and [GraphViz DOT](https://graphviz.org/docs/layouts/dot/)
15
-
<br>If there are more than 4000 classes + relationships, a simplified 3D viewer will be used to avoid slowdowns. Features will be toggleable in the 3D UI in a future release.
11
+
Code map viewers are powered by [3D Force Graph](https://vasturiano.github.io/3d-force-graph), [sigma.js](https://www.sigmajs.org/), and [GraphViz DOT](https://graphviz.org/docs/layouts/dot/) using [Vizdom](https://github.com/vizdom-dev/vizdom) to render the DOT graph.
12
+
<br>If there are more than 4000 classes + relationships, a simplified 3D viewer will be available to avoid page load slowdowns. Features will be toggleable in the 3D UI in a future release.
13
+
14
+
## How to Use RefactorFirst Quickly
15
+
Run the command below in your Java project's top-level directory. You'll need Git, Java 11 (or newer) and Maven 3 installed. This command will analyze Maven and non-Maven projects:
View the report at ```target/site/refactor-first-report.html``` in your project.
20
+
Full instructions for various usage scenarios are below.
21
+
Great effort has been taken to make both the analysis and page rendering times as fast as possible.
16
22
17
23
## Decomposing and Removing Cycles
18
24
Cycle analysis is performed with cutting-edge [Directed Feedback Vertex Set](https://dl.acm.org/doi/10.1145/3711669) and [Directed Feedback Arc Set](https://arxiv.org/abs/2208.09234)
19
25
algorithms to identify the optimal classes and relationships between classes for removal to get rid of cycles in your codebase.
20
-
These algorithms are powerful and will push your CPU to its limits for large codebases, though it does play nice and shouldn't slow your computer down.
21
-
These graph algorithms can be used outside RefactorFirst.
26
+
These algorithms are powerful and will push your CPU to its limits for large codebases, though they do play nice and shouldn't slow your computer down.
27
+
These graph algorithms can be used outside of RefactorFirst.
22
28
See [DIAGRAM.md](./graph-algorithms/src/main/java/org/hjug/feedback/vertex/kernelized/DIAGRAM.md) for the flow of the vertex kernelized algorithm.
23
29
See [DIAGRAM.md](./graph-algorithms/src/main/java/org/hjug/feedback/arc/pageRank/DIAGRAM.md) for more details on the arc kernelized algorithm.
24
30
25
31
26
32
### How to understand the Relationship Removal Priority table
27
33
28
-
The Relationship Removal Priority table shows the most optimal relationships to remove from your codebase to remove all cycles.
34
+
The Relationship Removal Priority tables shows the most optimal relationships to remove from your codebase to remove all cycles.
29
35
The table is sorted by the number of cycles that a relationship exists in and then the change proneness of the classes in the relationship.
30
-
- Classes that should be broken apart / removed from the codebase are bold.
31
-
- If only one class is bold, the shared functionality should be moved to the non-bold class.
32
-
- If neither class or both classes are bold, examine both classes and reassess the responsibilities of the classes and refactor to remove the relationship.
36
+
- Classes that should be broken apart / removed from the codebase have a *.
37
+
- If only one class is bold, the shared functionality should be moved to the non-bold class or classes.
38
+
- If neither class or both classes are bold: examine both classes carefully, reassess the responsibilities of the classes and then refactor to remove the relationship. If one or both classes are identified as a disharmony, follow the guidance provided for the disharmony.
33
39
34
40
Take a look at the [Spring Petclinic REST project sample report](https://rawcdn.githack.com/refactorfirst/RefactorFirst/c46d26211a91ffbe08d4089e04a85ff31eb093c0/spring-petclinic-rest-report.html)!
35
41
36
42
The graphs generated in the report will look similar to this one:
37
43
38
44
39
45
## Please Note: Java 11 (or newer) required to run RefactorFirst
40
-
**Java 21 codebase analysis is supported!**
41
-
The change to require Java 11 is needed to address vulnerability CVE-2023-4759 in JGit
46
+
**Java 25 codebase analysis is supported!**
42
47
Please use a recent JDK release of the Java version you are using.
43
48
If you use an old JDK release of your chosen Java version, you may encounter issues during analysis.
44
49
45
50
46
-
## There are several ways to run the analysis on your codebase:
47
-
51
+
## How to use RefactorFirst:
48
52
### From The Command Line As an HTML Report
49
53
Run the following command from the root of your project (the source code does not need to be built):
@@ -109,12 +113,31 @@ Specify with -D if running on the command line. e.g. ```-DbackEdgeAnalysisCount
109
113
|analyzeCycles|Analyzes the 10 largest cycles (will be configurable in the future)| true |
110
114
|minifyHtml|Minifies the generated HTML report. Only available on ```htmlReport``` and ```simpleHtmlReport``` goals. May cause issues with large reports.| false |
111
115
|excludeTests|Exclude test classes from analysis| true |
112
-
|testSrcDirectory|Excludes classes containing this pattern from analysis|```src/test```and ```src\test```|
116
+
|testSrcDirectory|Excludes classes containing this pattern from analysis|```src/test```|
113
117
|projectName|The name of your project to be displayed on the report| Your Maven project name |
114
118
|projectVersion|The version of your project to be displayed on the report| Your Maven project version |
115
119
|outputDirectory|The location the project report will be written| ```${projectDir}/target/site/refactor-first-report.html```
116
120
117
121
122
+
## But I'm using Gradle / my project layout isn't typical!
123
+
I plan to create a Gradle plugin and (possibly) support non-conventional project structures in the future, but in the meantime you can create a dummy POM file in the same directory as your .git directory to show your project's name in the report:
@@ -139,26 +162,6 @@ you will need to add the following to your pom.xml:
139
162
</build>
140
163
```
141
164
142
-
143
-
## But I'm using Gradle / my project layout isn't typical!
144
-
I would like to create a Gradle plugin and (possibly) support non-conventional projects in the future, but in the meantime you can create a dummy POM file in the same directory as your .git directory:
View the report at ```target/site/refactor-first-report.html```
164
167
Once the plugin finishes executing (it may take a while for a large / old codebase), open the file **target/site/refactor-first-report.html** in the root of the project. It will contain a graph similar to the one above, and a table that lists God classes in the recommended order that they should be refactored. The classes in the top left of the graph are the easiest to refactor while also having the biggest positive impact to team productivity.
@@ -182,13 +185,11 @@ There is still much to be done. Your feedback and collaboration would be greatl
182
185
If you find this plugin useful, please star this repository and share with your friends & colleagues and on social media.
183
186
184
187
## Future Plans
185
-
* Improve class cycle analysis
186
188
* Add a Gradle plugin.
187
189
* Incorporate Unit Test coverage metrics to quickly identify the safety of refactoring classes.
188
-
* Incorporate bug counts per class to the Impact (Y-Axis) calculation.
189
-
* Incorporate more disharmonies from Object Oriented Metrics In Practice (Lanza and Marinescu, 2004).
190
+
* Incorporate additional meaningful metrics.
190
191
191
192
## Note:
192
-
If you are a user of Version 0.1.0 or 0.1.1, you may notice that the list of God classes found by the plugin has changed. This is due to changes in PMD.
193
+
If you are a user of Version 0.8.0 or older, you may notice that the list of God classes found by the plugin has changed starting in version 0.9.0. This is due to the fact that the God class metric used starting with version 0.9.0 is faithful to the metric parameters defined in Object Oriented Metrics in Practice.
0 commit comments