In diesem Blogbeitrag werden wir:

• Suchen und Abgleichen von Anmerkungen demonstrieren
• Amen-Bemerkungen mit Schnurrbartvorlagen

Sensei bietet die Möglichkeit, problematische Codemuster abzugleichen und sie dann an vereinbarte Implementierungen anzupassen. In diesem Beispiel verwende ich @Disabled ohne einen Parameter als problematisches Codemuster.

Deaktivierte Testanmerkung

Deaktivierte Tests ohne angegebenen Grund können sich langfristig als problematisch erweisen, weil wir vergessen, warum wir sie deaktiviert haben.

@Disabled
   void thisTestMethodHasNoDisabledReason(){
    Assertions.fail("This test is disabled and should not run");
    }

Das Risiko besteht darin, dass sich die Codebasis im Laufe der Zeit weiterentwickelt, der deaktivierte Test nicht im Gleichschritt mit dem Zweck des Codes aktualisiert wird und schließlich redundant und irrelevant wird und möglicherweise nie wieder aktiviert wird.

Bei Code-Reviews werden wir oft darauf hinweisen, dass es sinnvoll ist, eine erklärende Beschreibung als Annotationsparameter hinzuzufügen.

@Disabled ("Disabled to demonstrate adding a reason")
    void thisTestMethodHasDisabledReason(){
   Assertions.fail("This test is disabled and should not run");
   }

Ein Sensei Rezept

Wir können ein Rezept schreiben, das erkennt, wenn @Disabled ohne Erklärung hinzugefügt wird, und einen Quick Fix, der uns daran erinnert, den tatsächlichen Grund für die Deaktivierung hinzuzufügen.

Wenn ich darüber nachdenke, was ich tun werde, muss ich es tun:

• entspricht der Disabled-Anmerkung ohne Parameter
• die Anmerkung "Disabled" so ändern, dass sie einen Parameter mit dem Markierungstext "TODO: fügen Sie hier eine Beschreibung ein" hat

Ein Warnrezept erstellen

Ich verwende Alt+Eingabe, um ein neues Rezept zu erstellen.

Fügen Sie dann den grundlegenden beschreibenden Text in den allgemeinen Informationen hinzu.

Wenn Sie die Regel zu einer Warnung machen, wird jeder übereinstimmende Code hervorgehoben, aber nicht als eklatanter Fehler angezeigt.

Finden Sie die Bemerkung

Im Rezepteditor ändere ich die Suche so, dass sie mit einer Bemerkung übereinstimmt.

Dadurch werden alle Anmerkungen in der Vorschau hervorgehoben.

Danach möchte ich nach dem Typ der Anmerkung filtern.

Ich könnte einfach Disabled verwenden, aber ich qualifiziere die Klasse vollständig mit dem Paket, sodass sie nur mit der Annotation von JUnit 5 übereinstimmt. Da der Quellcode in der Vorschau angezeigt wird, kann ich diesen einfach kopieren und aus dem eigentlichen Code einfügen, um Tippfehler zu vermeiden.

Ich möchte dann nur Annotationen ohne Parameter abgleichen, und das kann ich mit der GUI machen.

d.h. Suche:

search:
  annotation:
    type: "org.junit.jupiter.api.Disabled"
    without:
       parameters:
          - {}

Erstellen einer Aktion "Schnellreparatur neu schreiben

Für meinen QuickFix werde ich eine Rewrite-Aktion verwenden.

Ich verwende die Funktion " Variablen anzeigen", um mir die Mustache-Variablen anzeigen zu lassen und eine Vorschau des Inhalts zu erhalten.

Und dann füge ich den zusätzlichen Code hinzu, der benötigt wird, um den Platzmarkenkommentar zu erstellen.

d.h. QuickFix:

availableFixes:
 - name: "Add a todo comment parameter"
   actions:
   - rewrite:
      to: "{{{ . }}}(\"TODO: add a description here\")"
      target: "self"

Sensei in Aktion

Wir haben ein kurzes Video erstellt, das den Prozess der Rezepterstellung in Aktion zeigt.

Zusammenfassung

Beim Erstellen eines Rewrite-Quick-Fix ist es einfacher, wenn wir nach dem Code-Element suchen können, das wir umschreiben wollen, weil es dann die eigene Entität ist, auf die wir einwirken können.

In diesem Beispiel habe ich eine Rewrite-Aktion verwendet, um die Annotation zu ändern. Rewrite ist eine universelle Aktion, die auf jedes Code-Element angewendet werden kann und eine gute Voreinstellung ist, um sie zu erkunden.

Das Sensei Plugin bietet eine einfache Möglichkeit, bestimmte Codemuster in Ihrem Quellcode zu finden und dann Rewrite-Regeln anzuwenden, um den passenden Code zu ändern. Und das alles innerhalb der Intellij IDE und in Echtzeit.

‍

‍

Sie könnten zum Beispiel eine Regel erstellen, die auf JUnit `@Disabled` Annotationen passt, die keinen Grund haben. Sensei würde Sie dann über das Problem informieren, indem der Code in der IDE hervorgehoben wird.

Zusätzlich können Sie bei `alt+enter` die Option `Add a todo comment parameter` haben.

Wenn Sie diese Option auswählen, wird der Code so geändert, dass er einen Boilerplate-Grund hinzufügt, den Sie dann ändern können, und wenn Sie das nicht tun, wird er in Ihrem TODO-Bedienfeld angezeigt.

z.B. `@Disabled` würde zu ` @Disabled("TODO: füge hier eine Beschreibung ein")`

Sensei kombiniert die Funktionalität eines Static Analysis Code Scanners mit einer Code Rewriting Engine.

IntelliJ Intention-Aktionen

Basierend auf der obigen Beschreibung ist die offensichtliche Alternative (wenn Sie nicht Sensei verwenden würden) die Verwendung der IntelliJ Intention Actions-Funktionalität.

Sensei unterscheidet sich von IntelliJ Intention Actions, da das Ziel von Sensei darin besteht, eine Möglichkeit zum Erstellen von Matchern und Rewritern zu bieten, die projektspezifisch oder sogar lokal für einen einzelnen Entwickler sind.

Wir haben versucht, eine Benutzeroberfläche zusammenzustellen, mit der sowohl die Anpassungs- als auch die Umschreibungsregeln einfach zu schreiben und zu experimentieren sind.

Wie kann es mir persönlich helfen, mich zu verbessern?

Wenn ich eine neue Bibliothek lerne, brauche ich Zeit, um ein Muskelgedächtnis für die Methoden und die Formatierung aufzubauen. Ich könnte also persönliche Rezepte erstellen, die

• Verweis auf die offizielle Dokumentation oder Tutorialseiten
• haben Boilerplate-Vorlagen, die am effektivsten sind
• schlechte Kodierungspraktiken beheben
• Boilerplate-Code hinzufügen, um die Verwendung einer Bibliothek zu unterstützen

Ich kann Sensei verwenden, um temporäre Rezepte zu erstellen, die mich zu den aktuellen Praktiken, die ich gewählt habe, anregen und mir helfen, effektive Gewohnheiten aufzubauen. Und die Rezepte sind temporär, weil ich sie entfernen kann, wenn ich aus ihnen herausgewachsen bin.

Wie kann es meinem Team helfen, sich zu verbessern?

Auf die gleiche Weise können wir Teams helfen, ein Muskelgedächtnis für vereinbarte Codierungsstandards aufzubauen.

Erstellen von Kochbüchern mit Rezepten, die wir anwenden, wenn wir die gleichen Kommentare in Pull-Reviews finden. Da die Kochbücher in der Versionskontrolle mit dem Projekt gespeichert werden, sind sie für jeden im Projekt verfügbar. Und wir können sie ausschalten, wenn wir die Aufforderung nicht mehr brauchen.

Sensei hilft, frühzeitig Feedback zu geben

Was wir mit Sensei versucht haben, ist eine Möglichkeit, das Feedback, das uns hilft, uns zu verbessern, und Hinweise auf Korrekturmaßnahmen so früh wie möglich in den Codierungsprozess einzubringen.

Anstatt zu warten auf

• die Ergebnisse eines statischen Analysators
• die Kommentare aus einem Code-Review

Stattdessen können wir das Feedback für benutzerdefinierte Standards, die wir durchsetzen wollen, während des Programmierens sehen.

Und wir haben entweder Erinnerungshilfen oder tatsächliche Rewrite-Regeln, die uns helfen, Code zu schreiben, der den Standards entspricht.

Sensei ist flexibel

In dieser Hinsicht ist Sensei ein bisschen eine Mischung, denn es ist:

• Teil Statischer Analysator
• Kodierungstutor
• Umschreibemaschine

Sensei ist flexibel genug, um die Aufgabe "Was ist Sensei?" ein wenig schwieriger zu machen.

Sensei füllt eine Lücke im Programmier-Workflow

Wir haben versucht, Sensei zu dem fehlenden Teil des Arbeitsablaufs von Programmierern zu machen, der Ihnen hilft, bestimmte Elemente in Ihrem Codierungsstil oder bei der Verwendung von Bibliotheken zu verbessern, mit denen Sie und Ihr Team derzeit arbeiten.

Diese Flexibilität bedeutet, dass man etwas mehr Zeit braucht, um sich mit Sensei vertraut zu machen als mit einem statischen Analysetool oder den eingebauten IntelliJ Intentions. Dennoch werden Sie, wenn Sie die Zeit zum Experimentieren aufwenden, eine neue Möglichkeit gewinnen, Ihr Lernen in Ihrem persönlichen Entwicklungsprozess zu beschleunigen.

Wie kann man experimentieren?

Sobald Sie Sensei vom[Intellij Marketplace] heruntergeladen und installiert haben, können Sie

Der einfachste Weg, Sensei für sich arbeiten zu lassen, besteht darin, Ihren Codierungsprozess zu betrachten und zu berücksichtigen:

• In welcher Dokumentation schlagen Sie immer wieder nach?
  -- Sie könnten einige Sensei Rezepte hinzufügen, die auf diese Dokumentation zurückverweisen.
• Welche einfachen Fehler machen Sie immer wieder?
  -- Sie könnten dieses schlechte Codierungsmuster vorübergehend als Matcher kodieren und einen Quick-Fix-Rewrite schreiben, der den Code so abändert, dass er das ist, was Sie wirklich schreiben wollen.
• Welchen Boilerplate-Code schreiben Sie, um eine Bibliothek zu verwenden?
  -- Sie könnten eine Quick-Fix-Regel erstellen, um den Code für Sie zu schreiben.

Da Sensei so konzipiert ist, dass es mit dem von Ihnen verwendeten statischen Analysewerkzeug zusammenarbeitet, können Sie, wenn Sie feststellen, dass dieselben Verstöße von der statischen Analyse gemeldet werden, die Bedingung in einem Sensei Rezept replizieren. Sie können dann eine Schnellreparatur hinzufügen, die Ihnen hilft, nicht nur den Fehler zu identifizieren, sondern auch schnell zum Schreiben des richtigen Codes überzugehen

Ausführen von IntelliJ-Inspektionen aus der kontinuierlichen Integration

IntelliJ IDEA bietet Funktionen zur Verbesserung unserer Codierung, innerhalb der IDE beim Schreiben von Code als Intentions. Intentions können im Batch verwendet werden, um den Code auf Muster im gesamten Quellcode zu untersuchen und sogar auf die Befehlszeilenanalyse erweitert oder zur kontinuierlichen Integration hinzugefügt werden. Dieser Beitrag befasst sich mit der IntelliJ-Out-of-the-Box-Funktionalität und der Erweiterung mit benutzerdefinierten Intentions, die in Sensei erstellt wurden.

‍

IntelliJ-Prüfungen

Die Inspektionsfunktion von IntelliJ steuert die Anzeige vieler der Fehler, die dynamisch in der IDE beim Codieren gemeldet werden, z. B.

• Erkennung von abstrakten Klassen, die in Interfaces umgewandelt werden können,
• Identifizierung redundanter Klassenfelder, die lokal sein können,
• Warnung vor der Verwendung von veralteten Methoden,
• usw.

Diese Inspektionen markieren in der IDE übereinstimmenden Code als Intention Actions, die oft einen zugehörigen QuickFix haben.

Die Echtzeit-IDE, die hervorhebt, wenn Code mit einer Inspection übereinstimmt, kann uns helfen, unseren Code dynamisch zu verbessern. Nachdem das Problem im Code identifiziert wurde, kann die Verwendung von IntelliJ Intention Actions zum QuickFixen des Codes bessere Muster verstärken.

Inspektionen Profil

Inspektionen können als Batch aus der IDE, von der Kommandozeile oder in einem kontinuierlichen Integrationsprozess ausgeführt werden.

Der Schlüssel zur Arbeit mit IntelliJ-Inspektionen als Batch ist die Verwendung eines Inspektionsprofils.

IntelliJ hat zwei Standard-Prüfprofile: eines, das im Projekt gespeichert ist, und eines, das in der IDE gespeichert ist.

Neue Inspektionsprofile können erstellt werden, um bestimmte Plugins oder Anwendungsfälle zu konfigurieren, z. B.

• Nur Checkstyle-Echtzeit-Scan ausführen
• Ausführen eines bestimmten Satzes von Sensei Regeln
• Führen Sie die HTML-Prüfungen durch
  

Die Inspektionen in einem Profil können in den IntelliJ-Voreinstellungen aktiviert oder deaktiviert werden. Das Dialogfeld "Einstellungen" ist auch eine einfache Möglichkeit, den Umfang der verfügbaren Inspektionen kennenzulernen.

Mit dem "Werkzeug"-Symbol können Sie ein Profil duplizieren und ein neues Profil erstellen, um einen bestimmten Satz von Regeln zu erfassen.

Ausführen eines Inspektionsprofils in der IDE

Inspektionsprofile können aus der IDE heraus über das Menü "Analysieren" "Code inspizieren" ausgeführt werden.

Mit der Funktion "Analysieren" können Sie den Umfang der Inspektion steuern, z. B. das gesamte Projekt, einschließlich oder ausschließlich der Testquellen, oder eine bestimmte Gruppe von Dateien. 

Von hier aus können Sie auch die Inspektionsprofile verwalten, um ein bestimmtes Profil zu erstellen oder zu konfigurieren.

Wenn Sie im Dialog "Inspektionsumfang festlegen" auf [OK] klicken, veranlasst IntelliJ die Ausführung aller ausgewählten Inspektionen im Profil über den definierten Umfang.

IntelliJ meldet die Ergebnisse der ausgeführten Inspektionen auf der Registerkarte "Inspektionsergebnisse".

Das Sensei Plugin von Secure Code Warrior ermöglicht es Ihnen, benutzerdefinierte Code-Matching-Rezepte zu erstellen. Sensei ist eng mit IntelliJ integriert, so dass diese benutzerdefinierten Rezepte so natürlich wie die IntelliJ Intention Actions verwendet werden können. Das heißt, sie werden als Inspektionen in IntelliJ geladen und können mit Hilfe von Inspektionsprofilen gruppiert, aktiviert und deaktiviert werden. Das Erstellen eines benutzerdefinierten Inspektionsprofils und die anschließende Verwendung der Funktion "Analyze Inspect Code" ist der empfohlene Weg, um Sensei Rezepte in einem Projekt in großen Mengen auszuführen.

Ausführen eines Prüfprofils über die Befehlszeile

IntelliJ hat die Möglichkeit, Inspektionen von der Kommandozeile auszuführen, wie von JetBrains dokumentiert:

- https://www.jetbrains.com/help/idea/working-with-the-ide-features-from-command-line.html

Ich verwende hauptsächlich macOS und kann eine einzelne Instanz von IntelliJ von der Kommandozeile aus starten mit:

open -na "IntelliJ IDEA CE.app"

Um die Ausführung zu erleichtern, füge ich dies zu einem Shell-Befehlsskript hinzu.

vi /usr/local/bin/idea

Der Inhalt des Skripts stammt aus der offiziellen Dokumentation von IntelliJ.

#!/bin/sh
open -na "IntelliJ IDEA CE.app" --args "$@"

Ich habe dann diese ausführbare Datei erstellt, um den Prozess der Befehlszeileninspektion zu vereinfachen.

chmod 755 /usr/local/bin/idea

Die offizielle intellij-Dokumentation beschreibt die allgemeine Form des Inspektionsbefehls wie folgt:

idea inspect <project> <inspection-profile> <output></output></inspection-profile></project>
[<options>]</options>

In der Praxis qualifiziere ich die Pfade vollständig und benötige keine Optionen:

idea inspect /Benutzer/Benutzer/GitHub/sensei-blog-examples /Benutzer/Benutzer/GitHub/sensei-blog-examples/.idea/inspectionProfiles/senseiprofile.xml /Benutzer/Benutzer/GitHub/sensei-blog-examples/scan-results

Dies führt alle Inspektionen aus, die ich zum `senseiprofile` hinzugefügt habe und meldet die Ergebnisse im Ordner `scan-results`.

Anzeigen der Inspektionsergebnisse

Wir können diese Ergebnisse aus der Continuous Integration heraus melden, wie wir später sehen werden.

Wir können sie auch innerhalb von IntelliJ selbst anzeigen, indem wir die Funktion "Analyse" verwenden, um Offline-Inspektionsergebnisse anzuzeigen...

Dadurch werden die Ergebnisse in die Registerkarte "Inspektionsergebnisse" geladen.

Dies ist offiziell auf der JetBrains-Seite dokumentiert:

- https://www.jetbrains.com/help/idea/command-line-code-inspector.html#inspection-results

Dies könnte während eines Code-Review-Prozesses verwendet werden, wenn die Befehlszeilenausführung in einen kontinuierlichen Integrationsprozess eingebunden ist und die Reviewer den vollständigen Quellkontext eines beliebigen Eintrags des Inspektionsergebnisses überprüfen möchten.

Prüfprofile in der kontinuierlichen Integration

Wenn wir die Befehlszeileninspektion in die kontinuierliche Integration einbinden, wollen wir idealerweise, dass ein Bericht automatisch generiert wird, und es gibt eine Reihe von Optionen, die uns zur Verfügung stehen.

TeamCity bietet out of the box Unterstützung für Inspection Profiles in Continuous Integration.

- https://www.jetbrains.com/help/teamcity/inspections.html

Das Jenkins Warnings NG Plugin unterstützt die Kommandozeilenausgabe von IntelliJ Inspections als eines der Berichtsformate.

- https://github.com/jenkinsci/warnings-ng-plugin

- https://github.com/jenkinsci/warnings-ng-plugin/blob/master/SUPPORTED-FORMATS.md

Community-Projekte wie `idea CLI Inspector` existieren, um die Verwendung von Inspektionsprofilen in anderen CI-Werkzeugen zu unterstützen, z.B.

- https://github.com/bentolor/idea-cli-inspector

Die Zukunft von Inspection Profiles in einem CI-Prozess sieht mit der Einführung des Qodana-Projekts von JetBrains noch rosiger aus. Das Qodana-Projekt ist eine Headless-Version von IntelliJ mit offiziellen Github-Aktionen und Docker-Images.

- https://github.com/JetBrains/Qodana

Qodana befindet sich derzeit in der Betaphase, aber das Team von Sensei überwacht es, damit es eine offiziell unterstützte Plattform für die Ausführung von Sensei Regeln als Teil der kontinuierlichen Integration wird.

Zusammenfassung

Intention Actions ermöglichen es uns, Codierungsmuster zu verstärken und schnell in der IDE zu korrigieren, wenn wir beim Codieren Fehler machen.

Mit Inspection Profiles können wir diese in Profilen sammeln, die im Batch als Aktion "Analyze and Inspect Code" ausgeführt werden können. Dies kann nützlich sein, wenn wir auf ein Muster stoßen und doppelt überprüfen wollen, ob wir es irgendwo anders in unserem Code übersehen haben.

Inspection Profiles können von der Kommandozeile aus ausgeführt und sogar in Continuous-Integration-Prozesse eingebunden werden, die ein "Trust, but Verify"-Modell unterstützen und jeden versehentlichen Ausrutscher abfangen.

Alle oben genannten Funktionen sind in IntelliJ integriert und JetBrains verbessern ihren Continuous Integration Prozess mit der Einführung von Qodana.

Sensei Rezepte werden in IntelliJ geladen, um als native Intention Actions zu fungieren und in Inspection Profiles gesammelt zu werden, um die Batch-Prüfung durch Inspect Code und die Unterstützung der kontinuierlichen Integration durch die offizielle JetBrains Command Line Ausführungsfunktionalität zu unterstützen.

---

Sie können Sensei aus IntelliJ heraus über "Preferences \ Plugins" (Mac) oder "Settings \ Plugins" (Windows) installieren und dann einfach nach "sensei secure code" suchen.

Wenn Sie versuchen möchten, ein Projekt in IntelliJ von der Kommandozeile aus auszuführen, finden Sie das in diesem Beitrag verwendete Projekt im Repository "sensei-blog-examples" im GitHub-Konto Secure Code Warrior . Eine Übung für den Leser ist es, ein Profil zu erstellen, das nur die Sensei Regeln ausführt. Probieren Sie es aus:

https://github.com/securecodewarrior/sensei-blog-examples

Erfahren Sie mehr über Sensei