diff --git a/README.md b/README.md index 5901ebb..97512bd 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ Example Maven Project for a JavaFX Application. +**Update**: Added reporting to create a site (html documentation of project) + **Update**: Java 21 is now fully supported This projects includes multiple plugins: diff --git a/documentation/de/PMD.md b/documentation/de/PMD.md new file mode 100644 index 0000000..b694fcf --- /dev/null +++ b/documentation/de/PMD.md @@ -0,0 +1,61 @@ +# PMD + +## Regeln für PMD konfigurieren +In dem Projekt verwenden wir PMD, um die Code-Qualität sicherzustellen und +um allgemeine Fehler zu vermeiden. Die Regeln für die Codeanalyse sind in +der Datei pmd-ruleset.xml definiert, die im Hauptverzeichnis des Projekts +liegt. + +Diese Datei enthält spezifische Regelsätze, die an die Projektanforderungen +angepasst sind. Jeder Regelsatz innerhalb der pmd-ruleset.xml spezifiziert, +welche Probleme PMD im Code suchen und melden soll. Die Konfiguration umfasst +verschiedene Kategorien wie Fehlerprävention, Code-Stil, Optimierung und +viele andere. + +Ein typischer Eintrag in dieser Datei sieht wie folgt aus: + +```xml + + 5 + +``` +In diesem Beispiel wird die Regel UnusedImports aus dem Bereich der Best +Practices verwendet, um ungenutzte Importe im Code zu identifizieren. +Die Priorität dieser Regel ist auf 5 gesetzt, was einer niedrigen Priorität +entspricht. + +Um spezifische Bedürfnisse anzusprechen, können wir auch benutzerdefinierte +Regeln hinzufügen oder bestehende Regeln anpassen. Dies ermöglicht uns eine +flexible Anpassung der Codeanalyse, die dazu beiträgt, unseren Code sauber, +effizient und fehlerfrei zu halten. + +Für die effektive Nutzung von PMD ist es wichtig, dass alle Teammitglieder +verstehen, wie die pmd-ruleset.xml aufgebaut ist und wie sie zur Verbesserung +der Codequalität beiträgt. Daher sollte jeder Entwickler mit dieser +Konfigurationsdatei vertraut sein und wissen, wie Änderungen daran vorgenommen +werden. + +## Abbruch bei Regelverstößen + +In dem Maven-Projekt können wir durch das Festlegen spezifischer Ziele (Goals) +des Maven PMD oder Checkstyle Plugins steuern, ob der Build-Prozess bei +Verstößen gegen festgelegte Regeln abgebrochen werden soll. Diese Funktion +ist besonders nützlich, um die Code-Qualität sicherzustellen und Fehler +frühzeitig im Entwicklungsprozess zu erkennen. + +Je nach Konfiguration des Projekts können diese Ziele bei PMD gewählt werden: +- **pmd**: Bei Verstößen wird der weitere Build Prozess nicht abgebrochen +- **check**: Strengere Überprüfung und der Build Prozess bricht bei Vertsößen ab. + +Damit dies direkt in den Properties konfiguriert werden kann, wird die +Property pmd.target verwendet: +```xml +pmd +``` + +## Ergebnis der Analyse + +Das Ergebnis der Analyse findet sich nach der Überprüfung in target/pmd.xml. + +Um die Datei besser lesen zu können, sollte man sich die Datei einfach +von der Entwicklungsumgebung formatieren lassen. diff --git a/documentation/de/QuickStart.md b/documentation/de/QuickStart.md index 3540565..5a0d069 100644 --- a/documentation/de/QuickStart.md +++ b/documentation/de/QuickStart.md @@ -27,19 +27,31 @@ aufrufen. Um die Anwendung zu übersetzen kannst Du aufrufen: ```./mvnw package``` -### Bau des Images zur weitergabe +### Bau des Images zur Weitergabe Um das Image zu bauen, rufst du einfach Maven mit dem Profil Image und dem Ziel install auf: -```./mvnw -DImage install``` +```./mvnw -Dimage install``` **Wichtig** Du kannst nicht das JavaFX Plugin mit dem Ziel javafx:jlink verwenden, da dieses Plugin zwingend eine Modulbeschreibung für das Projekt und alle Abhängigkeiten erfordert. +### Komplette Übersetzung des Projekts incl. Dokumentation +Mit dem folgenden Befehl lässt sich das ganze Projekt von grundauf neu übersetzen incl. +der Erstellung der HTML Dokumentation des Projektes: +```./mvnw -Dimage clean install site``` + +- **-Dimage** aktiviert das Profil image, das für den Bau des Application Images zuständig ist +- **clean** Mit dem Ziel clean wird am Anfang alles, was bereits ggf. schon an Übersetzungen vorhanden ist, entfernt wird. +- **install** Durch install wird das ganze Projekt gebaut incl. Unit Tests, statischer Codeanalyse, ... +- **site** Es wird die Dokumentation des Projektes gebaut. + ## Ergebnisse der statischen Codeanalyse Die Codeanalyse läuft automatisch beim Bau des Projektes und die Ergebnisse finden sich in: - ./target/pmd.xml - ./target/spotbugsXml.xml + +Wenn die Site gebau wird, dann gibt es html Seiten mit den Ergebnissen von PMD und Spotbugs in der Site. \ No newline at end of file diff --git a/documentation/de/SpotBugs.md b/documentation/de/SpotBugs.md new file mode 100644 index 0000000..79bb357 --- /dev/null +++ b/documentation/de/SpotBugs.md @@ -0,0 +1,74 @@ +# SpotBugs + +## Verwendung der "null" Annotations + +In Java-Projekten ist es wichtig, potenzielle NullPointer-Exceptions zu +vermeiden, die durch den unsachgemäßen Umgang mit Null-Werten entstehen +können. Die Null Annotations von JetBrains bieten eine praktische Lösung, +um solche Probleme frühzeitig im Code zu erkennen und entsprechende Warnungen +über Tools wie Spotbugs zu erhalten. + +### Abhängigkeit +Die notwendigen Annotations sind u.a. in der Library von JetBrains +```xml + + org.jetbrains + annotations + ${jetbrains.annotations.version + compile + +``` + +### Verwendung der Annotations im Code +Nachdem die Bibliothek in deinem Projekt verfügbar ist, kannst du die +Annotations **@Nullable** und **@NotNull** verwenden, um anzugeben, ob eine +Methode oder Variable Null-Werte akzeptieren darf oder nicht. + +#### @NotNull +Die @NotNull Annotation wird verwendet, um anzugeben, dass ein Parameter, +eine lokale Variable, ein Feld oder eine Methode niemals den Wert null +annehmen sollte. Dies ist besonders wichtig in Methoden, die keine null +Werte verarbeiten können, da es andernfalls zu einer NullPointerException +führen könnte. Durch die Anwendung dieser Annotation kann deine +Entwicklungsumgebung oder ein statischer Code-Analyse-Tool wie SpotBugs oder +IntelliJ IDEA's integrierter Inspektor dich warnen, wenn es eine potenzielle +Verletzung dieser Bedingung gibt. + +**Anwendungsbeispiele für @NotNull:** +- Methodenparameter: Garantiert, dass übergebene Argumente nicht null sind. +- Methodenrückgabetyp: Stellt sicher, dass die Methode keinen null Wert zurückgibt. +- Felder: Verhindert, dass Klassenfelder auf null gesetzt werden. + +#### @Nullable +Die @Nullable Annotation wird verwendet, um zu kennzeichnen, dass eine +Variable, ein Parameter, ein Feld oder eine Methode null zurückgeben oder +null akzeptieren kann. Diese Annotation ist nützlich, um klarzustellen, dass +Methoden und Variablen sicher für den Umgang mit Nullwerten sind. Wenn eine +Variable oder Methode als @Nullable gekennzeichnet ist, sollten Entwickler +entsprechende Null-Checks durchführen, um NullPointerExceptions zu vermeiden. + +**Anwendungsbeispiele für @Nullable:** +- Methodenparameter: Erlaubt explizit, dass übergebene Argumente null sein können. +- Methodenrückgabetyp: Gibt an, dass die Methode möglicherweise null zurückgibt, und fordert den Aufrufer auf, dies zu überprüfen. +- Felder: Erlaubt, dass Klassenfelder auf null gesetzt werden können. + +### Allgemeine Richtlinien +**Konsistente Verwendung**: Es ist wichtig, diese Annotationen konsistent im +gesamten Code zu verwenden, um ihre Effektivität zu maximieren. +Inkonsistenzen können zu Fehlinterpretationen und Fehlern führen. +**Integration mit Tools**: Nutze Entwicklungswerkzeuge und statische +Code-Analyse-Tools, die diese Annotationen erkennen und respektieren +können, um die Sicherheit deines Codes zu erhöhen. +**Dokumentation und Team-Kommunikation**: Stelle sicher, dass alle +Teammitglieder die Bedeutung und den korrekten Einsatz dieser Annotationen +verstehen. Dies verbessert die Code-Qualität und verhindert Fehler in der +Zusammenarbeit. + +Durch den durchdachten Einsatz von @NotNull und @Nullable kannst du die Robustheit deines Codes signifikant steigern und sicherstellen, dass deine Anwendungen weniger anfällig für Laufzeitfehler durch unerwartete Null-Werte sind. + +## Ergebnis der Analyse + +Das Ergebnis der Analyse findet sich nach der Überprüfung in target/spotbugsXml.xml. + +Um die Datei besser lesen zu können, sollte man sich die Datei einfach +von der Entwicklungsumgebung formatieren lassen. diff --git a/documentation/de/_Index.md b/documentation/de/_Index.md index e246eea..b1d7c2f 100644 --- a/documentation/de/_Index.md +++ b/documentation/de/_Index.md @@ -8,8 +8,9 @@ - Überprüfung auf Aktualisierungen ## [Statische Codeanalyse](StaticCodeAnalysis.md) -- PMD -- SpotBugs +- [PMD](PMD.md) +- [SpotBugs](SpotBugs.md) ## Sonstiges +- Reporting - Lombok \ No newline at end of file diff --git a/documentation/en/PMD.md b/documentation/en/PMD.md new file mode 100644 index 0000000..7e39cd1 --- /dev/null +++ b/documentation/en/PMD.md @@ -0,0 +1,61 @@ +# PMD + +## Rules for PMD + +In this project, we use PMD to ensure code quality and prevent common +mistakes. The rules for code analysis are defined in the pmd-ruleset.xml +file located in the main directory of the project. + +This file contains specific rule sets tailored to the project requirements. +Each rule set within the pmd-ruleset.xml specifies what issues PMD should +look for and report in the code. The configuration includes various +categories such as error prevention, code style, optimization, and many +others. + +A typical entry in this file looks like this: + +```xml + + 5 + +``` + +In this example, the UnusedImports rule from the best practices category is +used to identify unused imports in the code. The priority of this rule is set +to 5, which indicates a low priority. + +To address specific needs, we can also add custom rules or modify existing +ones. This allows us a flexible adjustment of the code analysis, which helps +to keep our code clean, efficient, and error-free. + +For effective use of PMD, it is important that all team members understand +how the pmd-ruleset.xml is structured and how it contributes to improving +code quality. Therefore, every developer should be familiar with this +configuration file and know how to make changes to it. + +## Stop build process on rule violations + +In the Maven project, we can control whether the build process should be +aborted upon violations of specified rules by setting specific goals (Goals) +of the Maven PMD or Checkstyle plugins. This function is particularly useful +for ensuring code quality and detecting errors early in the development +process. + +Depending on the project configuration, these goals can be selected for PMD: + +- **pmd**: Violations do not cause the build process to be aborted +- **check**: Stricter verification and the build process is aborted upon +violations. + +To enable configuration directly in the properties, the pmd.target property is used: + +```xml +pmd +``` + + +## Result of Analysis + +The result can be found inside target/pmd.xml. + +Formatting the file will make it much easier to read. \ No newline at end of file diff --git a/documentation/en/QuickStart.md b/documentation/en/QuickStart.md index dff4353..0decbea 100644 --- a/documentation/en/QuickStart.md +++ b/documentation/en/QuickStart.md @@ -28,11 +28,20 @@ to build the application. ### Build the Image To build the image, the profile Image must be used: -```./mvnw -DImage install``` +```./mvnw -Dimage install``` **Important** You cannot build an image using the javafx plugin. The javafx plugin requires that you build a modular Java application and all dependencies providing a module description. +### complete build including documentation +To build the complete project from scratch and build all parts possible, you could use the following command: +```./mvnw -Dimage clean install site``` + +- **-Dimage** activates the profile image that is responsible to build the application image +- **clean** cleans everything of previous builds. +- **install** build the project (compile, build jar file, ...) +- **site** creates the html documentation of the project + ## Static code analysis results The static code analysis is done during the build of the application. The results can be found in diff --git a/documentation/en/SpotBugs.md b/documentation/en/SpotBugs.md new file mode 100644 index 0000000..86e3bd5 --- /dev/null +++ b/documentation/en/SpotBugs.md @@ -0,0 +1,73 @@ +# SpotBugs + +## Using "null" Annotations +In Java projects, it's important to avoid potential NullPointerExceptions +that can arise from improper handling of null values. JetBrains' Null +Annotations offer a practical solution to detect such issues early in the +code and receive corresponding warnings through tools like SpotBugs. + +### Dependency +The necessary annotations are included in the JetBrains library: + +```xml + + org.jetbrains + annotations + ${jetbrains.annotations.version} + compile + +``` + +### Using the Annotations in Code +Once the library is available in your project, you can use the **@Nullable** +and **@NotNull** annotations to indicate whether a method or variable can +accept null values. + +#### @NotNull +The @NotNull annotation is used to specify that a parameter, local variable, +field, or method should never accept a null value. This is especially +important in methods that cannot process null values, as it could lead to a +NullPointerException. By using this annotation, your development environment +or a static code analysis tool like SpotBugs or IntelliJ IDEA's integrated +inspector can warn you if there's a potential violation of this condition. + +**Examples of using @NotNull:** +- Method parameters: Ensures that passed arguments are not null. +- Method return types: Ensures that the method does not return a null value. +- Fields: Prevents class fields from being set to null. + +#### @Nullable +The @Nullable annotation is used to indicate that a variable, parameter, +field, or method can return or accept null. This annotation is useful to +clarify that methods and variables are safe for handling null values. If a +variable or method is marked as @Nullable, developers should perform +appropriate null checks to avoid NullPointerExceptions. + +**Examples of using @Nullable:** + +- Method parameters: Explicitly allows passed arguments to be null. +- Method return types: Indicates that the method may return null, prompting the caller to check. +- Fields: Allows class fields to be set to null. + +### General Guidelines +**Consistent Use**: It's important to use these annotations consistently +throughout the code to maximize their effectiveness. Inconsistencies can lead +to misinterpretations and errors. + +**Integration with Tools**: Use development tools and static code analysis +tools that can recognize and respect these annotations to enhance your code's +safety. + +**Documentation and Team Communication**: Ensure that all team members +understand the importance and correct use of these annotations. This improves +code quality and prevents errors in collaboration. + +By thoughtfully using @NotNull and @Nullable, you can significantly enhance +the robustness of your code and ensure that your applications are less +susceptible to runtime errors caused by unexpected null values. + +## Result of Analysis + +The result can be found inside target/spotbugsXml.xml. + +Formatting the file will make it much easier to read. diff --git a/documentation/en/_Index.md b/documentation/en/_Index.md index 6d2456a..cfd09a4 100644 --- a/documentation/en/_Index.md +++ b/documentation/en/_Index.md @@ -8,8 +8,9 @@ - Checking of Updates ## [Static Code Analysis](StaticCodeAnalysis.md) -- PMD -- FindBugs +- [PMD](PMD.md) +- [SpotBugs](SpotBugs.md) ## Other Topics +- Reporting - Lombok \ No newline at end of file diff --git a/pom.xml b/pom.xml index 3d24c94..1d7b63a 100644 --- a/pom.xml +++ b/pom.xml @@ -30,6 +30,9 @@ 5.11.0 + 2.16.2 + 0.0.8 + 0.1.5 3.3.2 3.13.0 3.6.1 @@ -37,14 +40,13 @@ 3.4.1 3.1.2 3.4.1 + 3.6.3 + 3.5.0 3.3.1 - 4.0.0-M13 + 4.0.0-M14 3.2.5 1.0.0.RC2 - 0.1.5 - 3.22.0 - 2.16.2 - 0.0.8 + 3.22.0 4.8.5.0 4.8.5 @@ -237,7 +239,7 @@ org.apache.maven.plugins maven-pmd-plugin - ${maven.pmd.version} + ${maven.pmd.plugin} 100 ${java.version} @@ -272,6 +274,20 @@ + + org.apache.maven.plugins + maven-javadoc-plugin + ${maven.javadoc.plugin} + + + attach-javadocs + + jar + + + + + org.openjfx @@ -284,17 +300,82 @@ + + + + org.apache.maven.plugins + maven-project-info-reports-plugin + ${maven.project.info.reports.plugin} + + + + index + dependencies + licenses + summary + + + + + + org.apache.maven.plugins + maven-javadoc-plugin + ${maven.javadoc.plugin} + + + + javadoc + + + + tests + + private + + + test-javadoc + + + + + + org.apache.maven.plugins + maven-pmd-plugin + ${maven.pmd.plugin} + + + + pmd + + + + + + com.github.spotbugs + spotbugs-maven-plugin + ${spotbugs.maven.plugin} + + + + spotbugs + + + + + + + - Image + image - Image + image