Documentation en Kotlin : écrire du code qui parle de lui-même

Documentation dans les projets Kotlin : l'art d'être compris

Imaginez : vous ouvrez un projet Kotlin écrit par quelqu'un d'autre. Le code est beau, concis, mais... vous ne comprenez pas à quoi sert cette fonction ni ce qu'elle retourne. Cela vous dit quelque chose ? Imaginez maintenant que ce projet est le vôtre, mais six mois plus tard. La documentation en Kotlin n'est pas seulement une politesse envers vos collègues. C'est un investissement dans l'avenir de votre code.

Dans cet article, nous allons explorer les meilleures pratiques de documentation des projets Kotlin. Vous apprendrez à utiliser KDoc, Dokka et les commentaires simples pour que votre code parle de lui-même. C'est parti !

Pourquoi la documentation en Kotlin n'est-elle pas ennuyeuse ?

Kotlin est un langage créé pour les humains. Il se lit comme de l'anglais et sa syntaxe élimine le code boilerplate. Mais même le code le plus élégant peut être une énigme sans documentation. Surtout lorsqu'il s'agit de :

\n
• Logiques métier complexes ;
\n
• Bibliothèques et API utilisées par d'autres développeurs ;
\n
• Projets Android avec un long cycle de vie ;
\n
• Solutions d'entreprise où le turnover est normal.
\n

Une bonne documentation Kotlin résout trois problèmes : elle explique « quoi » fait le code, « pourquoi » il le fait et « comment » l'utiliser. Sans elle, vous risquez d'avoir un code que personne ne veut toucher (même pas vous).

KDoc : l'outil principal de documentation Kotlin

KDoc est l'équivalent de JavaDoc pour Kotlin. Il utilise des commentaires de la forme /** ... */ et prend en charge Markdown. C'est le standard de facto pour la documentation dans les projets Kotlin.

Voici un exemple de base :

/**\n * Calcule la réduction pour un utilisateur en fonction de son statut.\n *\n * @param price Prix initial du produit.\n * @param userLevel Niveau de l'utilisateur (BRONZE, SILVER, GOLD).\n * @return Prix final après réduction.\n * @throws IllegalArgumentException Si price est négatif.\n */\nfun calculateDiscount(price: Double, userLevel: UserLevel): Double {\n    // logique\n}

Notez que KDoc utilise les balises @param, @return, @throws. Mais contrairement à JavaDoc, vous pouvez écrire du Markdown directement à l'intérieur du commentaire. C'est pratique pour les listes, les liens et le formatage.

Meilleures pratiques KDoc

\n
• Écrivez pour les humains, pas pour les machines. Ne dupliquez pas ce qui est évident dans le code. Au lieu de // définit la valeur, écrivez // Définit la valeur qui sera utilisée pour le calcul des impôts.
\n
• Documentez l'API publique. Les fonctions internes (private ou internal) peuvent être documentées brièvement ou pas du tout.
\n
• Utilisez @see et @sample. Référencez les fonctions associées ou des exemples d'utilisation.
\n
• N'oubliez pas @receiver pour les fonctions d'extension.
\n

Dokka : transformer les commentaires en belle documentation

Dokka est un générateur de documentation pour Kotlin. Il peut créer du HTML, du Markdown, du JavaDoc et même de la documentation pour les projets multiplateformes. Si vous écrivez une bibliothèque ou travaillez en équipe, Dokka est votre meilleur ami.

L'installation est simple. Dans build.gradle.kts, ajoutez le plugin :

plugins {\n    id("org.jetbrains.dokka") version "1.9.20"\n}

Ensuite, exécutez la commande :

./gradlew dokkaHtml

Dokka générera un dossier build/dokka/html avec une belle documentation incluant tous vos commentaires KDoc, la hiérarchie des classes et même des liens vers les sources.

Conseils pour Dokka

\n
• Configurez le logo et la description du projet dans dokkaConfiguration ;
\n
• Utilisez @suppress pour masquer les éléments indésirables