diKTat transforme la revue de code Kotlin en routine automatisée

Vous êtes-vous déjà trouvé dans une situation où un tiers des commentaires de vos pull requests portaient sur des disputes de formatage ? Quelqu'un a laissé un booléen négatif comme isNoError, quelqu'un a mélangé l'ordre des méthodes dans une classe, et quelqu'un a comparé des nombres à virgule flottante en utilisant l'opérateur ==. Techniquement le code compile et les tests passent, mais relire un tel code six mois plus tard devient physiquement douloureux.

D'habitude pour Kotlin, les équipes optent pour la combinaison ktlint et detekt. Le premier surveille l'indentation et l'espacement, le second cherche les odeurs de code évidentes. Mais il y a une zone grise entre eux en ce qui concerne le style architectural et les conventions, où les équipes soit écrivent leurs propres règles soit perdent du temps en commentaires manuels. Le dépôt diKTat de l'équipe SaveOurTool résout exactement ce problème.

Qu'est-ce que diKTat

Le projet est un ensemble strict de règles de conventions de code pour Kotlin. Techniquement, diKTat est construit au-dessus de ktlint et analyse l'AST des fichiers. Le dépôt contient un guide complet divisé en sections : nommage, commentaires KDoc, structure des classes, fonctions, travail avec les types et les variables.

L'outil inclut plus d'une centaines de vérifications, dont beaucoup ne se trouvent pas du tout dans d'autres analyseurs statiques. Le principal avantage est que diKTat peut non seulement se plaindre dans la console, mais aussi corriger automatiquement les violations trouvées à la volée.

Vérifications non évidentes qui sauvent votre code

La plupart des linters se concentrent sur le formatage. DiKTat creuse plus profond et détecte les bizarreries sémantiques.

Propreté du nommage et de la logique

DiKTat interdit par défaut les noms de variables à double négation. Si vous déclarez un flag val isNotValid = false, le linter exigera de le renommer en équivalent positif. Les constructions comme !isNotValid cassent le cerveau à la lecture, donc cette règle épargne les nerfs de tous.

Il vérifie également les appels de fonctions avec négation. Au lieu de !list.isEmpty(), l'outil suggérera persévéramment d'écrire list.isNotEmpty().

Ordre des membres de classe

Un problème courant dans les gros fichiers Kotlin est le désordre des champs, fonctions et objets. DiKTat contrôle strictement la structure :

• Constantes de temps de compilation
• Propriétés régulières
• Propriétés late-init
• Blocs init (et l'outil interdit de créer plusieurs blocs init sans nécessité explicite)
• Constructeurs
• Méthodes publiques, internes, protégées et privées
• Objet companion

Si quelqu'un place un helper privé avant l'API publique, le build CI échouera.

Sécurité des types et des calculs

L'outil interdit la comparaison directe des types Float et Double via ==. En raison des particularités de la représentation binaire des nombres à virgule flottante, de telles comparaisons mènent souvent à des bugs difficiles à détecter. DiKTat vous forcera à utiliser une vérification par delta via abs(a - b) > EPS ou à passer à BigDecimal.

Une autre vérification intéressante suit les casts redondants. Si Kotlin a déjà effectué un Smart Cast dans une condition, appeler as Type sera marqué comme un bruit inutile.

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

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

Comment exécuter et configurer

DiKTat peut être exécuté via le terminal, intégré dans les builds Gradle ou Maven, ou connecté via l'agrégateur Spotless.

Ajout à Gradle

Pour les projets utilisant Gradle avec Kotlin DSL, le plugin se connecte en quelques lignes :

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")
        }
    }
}

Les vérifications s'exécutent avec la commande ./gradlew diktatCheck, et la correction automatique de tout ce que l'analyseur peut atteindre se fait via ./gradlew diktatFix.

Réglage fin des règles

La configuration réside dans un fichier YAML standard diktat-analysis.yml. Chaque règle est activée ou désactivée séparément, et beaucoup ont des paramètres spécifiques :

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]

Si vous avez besoin de supprimer une vérification spécifique localement, l'annotation standard @Suppress("FUNCTION_NAME_INCORRECT_CASE") ou un @Suppress("diktat") général fonctionne directement dans le code.

Adoption progressive via Baseline

Activer un linter strict sur un ancien projet avec 50 000 lignes de code sans préparation est impossible. Les développeurs se noieraient dans des milliers d'avertissements.

Pour cela, diKTat dispose d'un mode baseline. Lors de la première exécution, l'utilitaire génère un fichier XML avec tous les problèmes actuels du projet :

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

Le fichier baseline est commité dans le dépôt. Après cela, le linter cesse de se plaindre de l'ancien code et bloque uniquement le build si quelqu'un introduit de nouvelles violations dans un commit frais.

Intégration avec GitHub Actions

L'outil peut produire des rapports au format SARIF. Combiné avec GitHub Actions, les erreurs et avertissements de style sont mis en évidence directement dans l'interface de la pull request avec des références de lignes exactes. Pas besoin de configurer des bots tiers pour les commentaires.

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

Cela vaut-il le coup d'essayer

DiKTat est très intransigeant. Son guide exige un ordre d'import explicite, limite la longueur des fonctions à trente lignes, contrôle la présence de documentation KDoc pour les méthodes publiques, et interdit les var inutiles.

Pour un projet personnel avec deux personnes, de telles restrictions sembleront excessives. Mais si une équipe distribuée travaille sur un service ou si vous développez une bibliothèque open source, diKTat supprime les maux de tête de la synchronisation du style et libère du temps de revue de code pour discuter d'architecture plutôt que d'espaces. Le moyen le plus simple de commencer est d'ajouter le plugin Gradle en mode vérification mono-module et de générer un baseline.