Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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: 5 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 (21 days ago)
- Default Branch: main
- Last Pushed: 2024-10-25T12:00:52.000Z (13 days ago)
- Last Synced: 2024-10-25T13:51:34.932Z (13 days 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
[](https://maven-badges.herokuapp.com/maven-central/io.github.ihepda/techdebt-processor)
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.
## 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:
```
io.github.ihepda
tech-debt-annotations
1.0.0
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:
```
@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
```
@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}
```
@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 tech-debt: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*
```
io.github.ihepda
tech-debt-maven-plugin
1.0.0-SNAPSHOT
org.apache.maven.plugins
maven-site-plugin
3.12.1
```
### Conclusion
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.
## Examples
Please see the example in **example** folder