Conventions de codage et de documentation Java

de | 22 février 2016
0 Commentaire

Google Java Style

Dans vos projets de développement en Java, nous vous recommandons de respecter les conventions de codage décrites dans le style Java de Google, en utilisant une limite de longueur de ligne de 100 caractères (le style Google laissant le choix entre une limite de 80 ou 100 caractères).

Cette convention implique notamment l’utilisation de Javadoc et des outils associés pour l’écriture et la génération de la documentation du code.

Comme cette convention de codage est assez large et couvre de nombreux aspects, il peut être difficile de la respecter scrupuleusement lors de l’écriture du code. Afin de vous assurer du respect de la convention, nous vous recommandons très fortement l’utilisation d’un outil de vérification automatique de style.

Pour vous assurer du respect du style Java de Google, vous pouvez en particulier utiliser le logiciel Checkstyle. Sa mise en œuvre est décrite dans la section ci-dessous.

Alternativement, si vous utilisez les environnements de développement (IDE) Eclipse ou IntelliJ IDEA, vous pouvez directement configurer votre IDE pour qu’il vérifie le style Java de Google. Pour connaître la mise en œuvre, consultez la section concernant Eclipse ou IntelliJ IDEA.

Checkstyle

Pour télécharger Checkstyle, consultez cette page.

Si vous utilisez une distribution GNU/Linux Debian ou dérivée (notamment Ubuntu), vous pouvez installer facilement Checkstyle avec le paquet checkstyle :
sudo apt-get install checkstyle

Checkstyle peut être utilisé comme une tâche pour ANT ou en ligne de commande. Des greffons sont également disponibles pour utiliser Checkstyle dans de nombreux outils, notamment NetBeans, Maven et Gradle.

Pour vérifier que votre code respecte le style Java de Google, assurez-vous de bien utiliser la feuille de style google_checks.xml. Si elle n’est pas directement disponible dans votre installation de Checkstyle, vous pouvez la récupérer depuis le projet Checkstyle sur GitHub à cette adresse.

Attention, il faut s’assurer de bien récupérer une version de la feuille de style compatible avec la version de Checkstyle installée. Par exemple sous Ubuntu 15.10 où la version installable de Checkstyle est la 5.9, il est nécessaire de récupérer le fichier google_checks.xml à l’adresse suivante. Pour obtenir le fichier pour d’autres versions, il est possible de consulter cette page ou cette page et de modifier la branche affichée pour choisir le tag correspondant à la version de Checkstyle souhaitée.

Typiquement, l’utilisation en ligne de commande de Checkline se fait de la façon suivante pour analyser un unique fichier :

>>> checkstyle -c /tmp/google_checks.xml /tmp/AgentGenerator.java
Starting audit...
/tmp/AgentGenerator.java:4: warning: Import statement is in the wrong order. Should be in the 'THIRD_PARTY_PACKAGE' group.
/tmp/AgentGenerator.java:5: warning: Import statement is in the wrong order. Should be in the 'THIRD_PARTY_PACKAGE' group.
/tmp/AgentGenerator.java:8:10: warning: Le mot-clef 'public' n'apparaît pas dans l'ordre préconisé par les JLS.
/tmp/AgentGenerator.java:8:75: warning: GenericWhitespace '>' should followed by whitespace.
/tmp/AgentGenerator.java:9: warning: La ligne excède 100 caractères.
/tmp/AgentGenerator.java:9: warning: method def modifier au niveau d'indentation 4 n'est pas indenté correctement (2)
/tmp/AgentGenerator.java:9:14: warning: Le mot-clef 'public' n'apparaît pas dans l'ordre préconisé par les JLS.
Audit done.

On voit que la sortie indique les lignes qui ne respectent pas la convention ainsi que les problèmes identifiés sur ces lignes.

Pour appliquer l’analyse à l’ensemble des fichiers d’un répertoire, utiliser l’option -r :
checkstyle -c /tmp/google_checks.xml -r /tmp/src/

Eclipse

Pour permettre à Eclipse de vérifier le respect du style Java de Google, il faut récupérer ce fichier de configuration.

Pour utiliser ce fichier de configuration dans Eclipse :

  • ouvrir le menu Window/Preferences,
  • sélectionner Java/Code Style/Formatter,
  • importer le fichier de configuration en cliquant sur le bouton Import…,
  • sélectionner GoogleStyle comme profil actif et valider ce choix.

Puis pour appliquer automatiquement le style sur un fichier, utiliser le menu Source/Format.

IntelliJ IDEA

Pour permettre à IntelliJ IDEA de vérifier le respect du style Java de Google, il faut récupérer ce fichier de configuration.

Pour utiliser ce fichier de configuration dans IntelliJ IDEA :

  • copier le fichier de configuration de style dans le répertoire de configuration d’IntelliJ IDEA (sous Linux, ce répertoire devrait être de la forme ~/.IdeaICXX/config/codestyles/ avec XX la version installée d’IntelliJ IDEA, sous Mac OS il devrait être de la forme $HOME/Library/Preferences/IdeaICXX/codestyles),
  • ouvrir le menu File/Settings…
  • sélectionner Editor/Code Style/Java,
  • sélectionner GoogleStyle comme schéma courant et valider ce choix.