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/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..7a20fb4 100644 --- a/documentation/de/_Index.md +++ b/documentation/de/_Index.md @@ -8,8 +8,8 @@ - Überprüfung auf Aktualisierungen ## [Statische Codeanalyse](StaticCodeAnalysis.md) -- PMD -- SpotBugs +- [PMD](PMD.md) +- [SpotBugs](SpotBugs.md) ## Sonstiges - 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/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..6a69840 100644 --- a/documentation/en/_Index.md +++ b/documentation/en/_Index.md @@ -8,8 +8,8 @@ - Checking of Updates ## [Static Code Analysis](StaticCodeAnalysis.md) -- PMD -- FindBugs +- [PMD](PMD.md) +- [SpotBugs](SpotBugs.md) ## Other Topics - Lombok \ No newline at end of file