https://github.com/ihepda/java-tech-debt
Annotations and reporting tool in order to mark technical debt issues
https://github.com/ihepda/java-tech-debt
java maven reporting technical-debt
Last synced: 6 days ago
JSON representation
Annotations and reporting tool in order to mark technical debt issues
- Host: GitHub
- URL: https://github.com/ihepda/java-tech-debt
- Owner: ihepda
- License: apache-2.0
- Created: 2024-10-17T09:27:57.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2024-10-25T12:00:52.000Z (9 months ago)
- Last Synced: 2024-10-25T13:51:34.932Z (9 months ago)
- Topics: java, maven, reporting, technical-debt
- Language: Java
- Homepage: https://ihepda.github.io/java-tech-debt/
- Size: 74.2 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# java-tech-debt
| Resource | Status |
| ---- | ------ |
|Parent project|[](https://central.sonatype.com/artifact/io.github.ihepda/tech-debt-parent)|
|Annotation project|[](https://central.sonatype.com/artifact/io.github.ihepda/tech-debt-annotation)|
|Processor project|[](https://central.sonatype.com/artifact/io.github.ihepda/tech-debt-processor)|
|Maven plugin project|[](https://central.sonatype.com/artifact/io.github.ihepda/tech-debt-maven-plugin)|
The *java-tech-debt* project is an annotation and reporting tool designed to identify and manage technical debts in code. Technical debts are an inevitable reality in software development, often overlooked or forgotten over time.
## Why Technical Debts Matter
Technical debts represent compromises in the code that, if unmanaged, can lead to maintenance and scalability issues. Often, these debts are noted in external tools like Jira or ClickUp, but other times they are completely forgotten, accumulating and further complicating the development process.
## Project Features
* **Annotations**: Allows marking parts of the code that contain technical debts.
* **Reporting**: Generates detailed reports to monitor and manage technical debts over time.
## Conclusion
The java-tech-debt project offers an effective solution to keep code clean and manageable, helping development teams track technical debts and plan refactoring efforts in a more structured and informed way.
Annotating technical debts directly in the code with **java-tech-debt** helps keep the code clean and manageable. Following these steps will allow you to track technical debts and plan refactoring efforts in a more structured way.
## Marking Technical Debts with java-tech-debt
### Introduction
The **java-tech-debt** project allows you to annotate and manage technical debts directly in your code. This tutorial will guide you through the steps needed to mark technical debts using the annotations provided by the project.
### Step 1: Add the Maven Dependency
Ensure you have the **java-tech-debt** dependency in your *pom.xml* file:
```xml
io.github.ihepda
tech-debt-annotation
1.0.1
compile
true
```
Remember to set the scope to **compile** and the **optional** tag to true. This configuration will use this library only in compilation phase and it won't be added as runtime dependency.
### Step 2: Import the Annotation
In your Java file, import the necessary annotation:
import io.github.ihepda.techdebt.annotations.TechDebt;
### Step 3: Annotate the Code with Technical Debts
Use the annotation to mark technical debts in your code. Here is an example:
```java
@TechDebt(
description = "Refactor this method to improve readability",
date = "2024-10-28",
owner = "[email protected]",
severity= Severity.MAJOR
)
public void someMethod() {
// Code that needs refactoring
}
```
You can use a single annotation or multiple annotation
```java
@TechDebt(severity = Severity.MAJOR, comment = "classe")
@TechDebt(severity = Severity.MINOR, comment = "minor class", effort = Effort.MASSIVE, type = Type.PERFORMANCE)
public class MyClass {
```
You can mark issues in statement blocks, unfortunately you can't use annotation in statement but **java-tech-debs** supply a method to mark some statement blocks using the *refComment* attribute.
With the *refComment* you can mark a comment as a technical debt comment that the system will use to identify the location of the block to mark, in the example the *refComment="AX"* indicates a block that starts with a comment @TD-AX and ends with a line comment #TD-AX (AX is the code).
Important is: the start block is a multi-line java comment (not javadoc comment) with the first line that contains the block code @TD-{code}, all comment below this row will be used to set the *comment* attribute in the tecnical debt information.
The end of the block must be a single line comment starts with #TD-{code}
```java
@TechDebt(
comment = "strange method2",
author = "CDA",
severity = TechDebt.Severity.TRIVIAL,
type = Type.MAINTAINABILITY,
effort = Effort.MASSIVE,
refComment = "AX")
public void execute2(Map params) {
@TechDebt(comment = "bad variable", author = "me", severity = TechDebt.Severity.MAJOR)
var a = 10;
var b = 20;
/*
* @TD-AX
* This is a test comment for AX
*
* to check
*/
this.execute(null);
// #TD-AX
this.execute(null);
}
```
### Step 4: Generate Reports
Once you have annotated the code, you can generate reports to monitor and manage technical debts. Run the Maven command to generate the report:
mvn io.github.ihepda:tech-debt-maven-plugin:report
or
mvn site
This command will analyze the annotations in your code and generate a detailed report of the technical debts.
Or, you can add the plugin in the *reporting* section of your *pom.xml*
```xml
io.github.ihepda
tech-debt-maven-plugin
1.0.1
org.apache.maven.plugins
maven-site-plugin
3.12.1
```
#### Filtering
issue: [Add report filter](https://github.com/ihepda/java-tech-debt/issues/6)
The report permits to set a filter in order to match only interested technical debts, for example technical debts sith a severity MAJOR or CRITICAL.
The filter is an 'SQL like filter', this is, you can use:
* common operators : =, !=, <=, <, >=, >
* like operator with or without the not keyword
* in operator with or without the not keyword
* and or conjunctions
* grouping expression with '(' and ')'
Below an example
```txt
comment like '%test%' and severity >= 'MAJOR' or author in ('CDA', 'LA')
comment not like '%test%' and (severity = 'MAJOR' or author not in ('CDA', 'LA'))
```
In order to activate the filter you have to add the *filter* configuration in the plugin
```xml
io.github.ihepda
tech-debt-maven-plugin
1.0.1
comment like '%test%'
org.apache.maven.plugins
maven-site-plugin
3.12.1
```
#### Blocking the build
issue: [Blocking the build if there are techdebts](https://github.com/ihepda/java-tech-debt/issues/11)
The maven plugin permits to block the build if same conditions are present. These conditions are defined
using a filter configuration. Below an example of filter configuration.
```xml
io.github.ihepda
tech-debt-maven-plugin
1.0.2-SNAPSHOT
check
severity.major > 10
```
The query language availabel is represented below:
As identifier you can use:
* ALL => Indicates all technical debts present in the project
* SEVERITY.{severity value} => searches for all technical debts with a specific severity value
* type.{type value} => searches for all technical debts with a specific type value
In the query language you are free to use _AND_, _OR_ and parenthesis, in order to compose complex conditions.
For example:
```txt
severity.major > 10
severity.major > 10 or type.security >=1
all > 20 or (type.security > 0 and severity.trivial >0)
```
## Examples
Please see the example in **example** folder