diKTat macht Kotlin Code Review zur automatisierten Routine

Warst du schon einmal in der Situation, dass ein Drittel deiner Pull-Request-Kommentare Formatierungsstreitigkeiten waren? Jemand hat eine negative Boolean-Variable wie isNoError hinterlassen, jemand hat die Reihenfolge der Methoden in einer Klasse durcheinandergebracht, und jemand hat Fließkommazahlen mit dem ==-Operator verglichen. Technisch gesehen kompiliert der Code und die Tests bestehen, aber ein halbes Jahr später wird das Lesen eines solchen Codebases körperlich schmerzhaft.

Normalerweise verwenden Teams für Kotlin die Kombination aus ktlint und detekt. Das erste behält Einrückungen und Abstände im Auge, das zweite sucht nach offensichtlichen Code-Smells. Aber es gibt einen Graubereich dazwischen, wenn es um Architekturstil und Konventionen geht, wo Teams entweder ihre eigenen Regeln schreiben oder Zeit mit manuellen Kommentaren verschwenden. Das diKTat-Repository vom SaveOurTool-Team löst genau dieses Problem.

Was ist diKTat

Das Projekt ist ein strenger Satz von Codekonventionsregeln für Kotlin. Technisch gesehen ist diKTat auf ktlint aufgebaut und analysiert den AST von Dateien. Das Repository enthält einen umfangreichen Leitfaden, der in Abschnitte unterteilt ist: Benennung, KDoc-Kommentare, Klassenstruktur, Funktionen, Arbeiten mit Typen und Variablen.

Das Tool enthält über hundert Checks, von denen viele in anderen statischen Analysatoren überhaupt nicht zu finden sind. Der Hauptvorteil ist, dass diKTat nicht nur in der Konsole meckern, sondern auch gefundene Verstöße spontan automatisch beheben kann.

Nicht-offensichtliche Checks, die deinen Code retten

Die meisten Linter konzentrieren sich auf Formatierung. DiKTAT geht tiefer und fängt semantische Unstimmigkeiten ab.

Sauberkeit von Benennung und Logik

DiKTat hat ein eingebautes Verbot für doppelt-negative Variablennamen. Wenn du ein Flag val isNotValid = false deklarierst, wird der Linter umbenennen in eine positive Entsprechung verlangen. Konstrukte wie !isNotValid brechen einem beim Lesen das Gehirn, also spart diese Regel jedermanns Nerven.

Es prüft auch Funktionsaufrufe mit Negation. Statt !list.isEmpty() wird das Tool hartnäckig vorschlagen, list.isNotEmpty() zu schreiben.

Reihenfolge von Klassenmitgliedern

Ein häufiges Problem in großen Kotlin-Dateien ist das Chaos aus Feldern, Funktionen und Objekten. DiKTat kontrolliert die Struktur streng:

• Kompilierzeitkonstanten
• Reguläre Properties
• Late-init-Properties
• Init-Blöcke (und das Tool verbietet das Erstellen mehrerer init-Blöcke ohne explizite Notwendigkeit)
• Konstruktoren
• Public-, Internal-, Protected- und Private-Methoden
• Companion-Object

Wenn jemand einen privaten Helfer vor die öffentliche API setzt, schlägt der CI-Build fehl.

Typ- und Berechnungssicherheit

Das Tool verbietet direkte Vergleiche von Typen Float und Double über ==. Aufgrund der Besonderheiten der binären Darstellung von Fließkommazahlen führen solche Vergleiche oft zu schwer zu findenden Bugs. DiKTat zwingt dich, Delta-Prüfung über abs(a - b) > EPS zu verwenden oder auf BigDecimal umzusteigen.

Ein weiterer netter Check verfolgt redundante Casts. Wenn Kotlin bereits einen Smart Cast innerhalb einer Bedingung durchgeführt hat, wird der Aufruf von as Type als unnötiges Rauschen markiert.

// Было
if (x is String) {
    print((x as String).length)
}

// Стало после автофикса
if (x is String) {
    print(x.length)
}

Wie man es ausführt und konfiguriert

DiKTat kann über das Terminal ausgeführt, in Gradle- oder Maven-Builds integriert oder über den Spotless-Aggregator angebunden werden.

Zu Gradle hinzufügen

Für Projekte, die Gradle mit Kotlin DSL verwenden, wird das Plugin in ein paar Zeilen angebunden:

plugins {
    id("com.saveourtool.diktat") version "2.0.0"
}

diktat {
    inputs {
        include("src/**/*.kt")
        exclude("src/test/kotlin/excluded/**")
    }
    reporters {
        plain()
        html {
            output = file("build/reports/diktat.html")
        }
    }
}

Checks werden mit dem Befehl ./gradlew diktatCheck ausgeführt, und alles, was der Analyzer erreichen kann, wird automatisch behoben über ./gradlew diktatFix.

Feintuning der Regeln

Die Konfiguration lebt in einer Standard-YAML-Datei diktat-analysis.yml. Jede Regel wird separat aktiviert oder deaktiviert, und viele haben spezifische Parameter:

name: HEADER_MISSING_OR_WRONG_COPYRIGHT
  enabled: true
  configuration:
    isCopyrightMandatory: true
    copyrightText: Copyright (c) MyTeam, 2024. All rights reserved.

name: HEADER_NOT_BEFORE_PACKAGE
  enabled: true
  ignoreAnnotated: [Generated, Controller]

Wenn du einen bestimmten Check lokal unterdrücken musst, funktioniert die Standard-Annotation @Suppress("FUNCTION_NAME_INCORRECT_CASE") oder ein allgemeines @Suppress("diktat") direkt im Code.

Schrittweise Einführung über Baseline

Ein strenges Linter auf einem alten Projekt mit 50.000 Zeilen Code ohne Vorbereitung zu aktivieren, ist unmöglich. Entwickler würden in Tausenden von Warnungen ertrinken.

Dafür hat diKTat einen Baseline-Modus. Beim ersten Lauf generiert das Tool eine XML-Datei mit allen aktuellen Problemen im Projekt:

./diktat --baseline=diktat-baseline.xml "src/**/*.kt"

Die Baseline-Datei wird ins Repository eingecheckt. Danach beschwert sich der Linter nicht mehr über alten Code und blockiert den Build nur, wenn jemand neue Verstöße in einem frischen Commit einführt.

GitHub Actions-Integration

Das Tool kann Berichte im SARIF-Format ausgeben. In Kombination mit GitHub Actions werden Style-Fehler und Warnungen direkt in der Pull-Request-Oberfläche mit genauen Zeilenverweisen hervorgehoben. Keine Notwendigkeit, Bots von Drittanbietern für Kommentare zu konfigurieren.

name: Upload SARIF report
  uses: github/codeql-action/upload-sarif@v1
  if: always()
  with:
    sarif_file: build/reports/diktat/diktat.sarif

Lohnt es sich, es zu versuchen

DiKTat ist sehr kompromisslos. Sein Leitfaden erfordert explizite Import-Reihenfolge, begrenzt die Funktionslänge auf dreißig Zeilen, kontrolliert die KDoc-Dokumentationspräsenz für öffentliche Methoden und verbietet unnötige var.

Für ein Hobbyprojekt mit zwei Personen werden solche Einschränkungen übertrieben erscheinen. Aber wenn ein verteiltes Team an einem Service arbeitet oder du eine Open-Source-Bibliothek entwickelst, entfernt diKTat die Kopfschmerzen der Stil-Synchronisation und befreit die Code-Review-Zeit für die Diskussion von Architektur statt Leerzeichen. Der einfachste Weg zu starten ist, das Gradle-Plugin im Single-Module-Check-Modus hinzuzufügen und eine Baseline zu generieren.