Pourquoi faire une documentation (avec quelques idées de contenu)

Vous êtes chargé de nourrir une équipe de 5 personnes en préparant une omelette aux champignons. Vous devez aller cueillir les-dits champignons en forêt, il vous en faut quelques kilos et vous n’y connaissez rien en terme de comestibilité (ni toxicité). Prendriez-vous un livre sur le sujet ?

Il est fréquent de constater que dans le milieu professionnel on recommande de demander aux personnes qui s’y connaissent où de trouver par soi même. On vous demande donc de partir en forêt avec une équipe, voir tout le village, pour savoir quel champignon cueillir et ceux à éviter. Si ils n’ont pas la réponse il suffira de faire goûter un extrait à quelqu’un pour en déterminer la nocivité (modification de code à l’aveugle).

La documentation d’un projet est souvent négligée au point de devoir en référer aux personnes ayant contribué au code ou, quand elles sont absente/parties, comprendre par vous même. Ce comportement peut entrainer un mauvais usage des fonctions existantes ou la création de régression. Pourtant elle est tout aussi importante que les tests sur un projet logiciel et même si on la comprend dans le bagage qualité, rangé au niveau facultatif faute de temps, elle est d’un avis plus personnel, inhérente au développement.

Lire la suite

Installer et utiliser SonarQube en 5 minutes

SonarQube est une application open-source regroupant sous forme de plugins divers outils permettant de définir la qualité du code source d’un projet (couverture du code par les tests, duplication de code, respect des conventions, …).

Nous allons voir ici comment déployer très rapidement cet outil dans sa version 4.1.2 sur un poste Debian, sans avoir à l’installer et de lancer une analyse rapide d’un projet. SonarQube nécessite cependant Java pour fonctionner.

Cette opération se résume en 5 étapes:

  1. Téléchargement de SonarQube et lancement du service
  2. Télechargement de SonarQube Runner
  3. Création du fichier de configuration
  4. Ajout du plugin PHP
  5. Lancement de l’analyse
  6. Résultats

Téléchargement de SonarQube et lancement du service

wget http://dist.sonar.codehaus.org/sonar-3.7.4.zip
unzip sonar-3.7.4.zip
cd sonar-3.7.4
sh bin/{version linux}/sonar.sh console

Téléchargement de SonarQube Runner

wget http://repo1.maven.org/maven2/org/codehaus/sonar/runner/sonar-runner-dist/2.3/sonar-runner-dist-2.3.zip
unzip sonar-runner-dist-2.3.zip

Fichier de configuration

Allez à la racine de votre projet puis créez un fichier sonar-project.properties

vim sonar-project.properties

Remplissez le avec les lignes suivantes

# Required metadata
sonar.projectKey=MonProjet
sonar.projectName=MonProjet
sonar.projectVersion=0.1

sonar.sources=app
sonar.language=php
sonar.sourceEncoding=UTF-8
sonar.php.tests.reportPath=tests.xml
  • Les trois premières lignes concernent le nom du projet et sa version.
  • La ligne source est le chemin relatif (à partir de la base de votre projet et donc du fichier de configuration) où se trouvent le code source de l’application, ici app (framework CakePHP)
  • On précise le language de programmation utilisé
  • et l’encodage des sources
  • la dernière ligne permet de spécifier le fichier de résultats des tests (format junit) généré par exemple via Jenkins.

Installation d’un plugin (ici PHP)

Seul le langage Java est utilisé par défaut, on va donc aller activer des modules pour gérer un autre langage. Pour cela il suffit d’aller sur l’interface d’administration avec un navigateur web sur l’adresse :

http://localhost:9000

De cliquer sur Login (menu du haut) et de rentrer les identifiants : admin / admin

Pour ajouter un plugin on va

  • suivre les menus Settings /Update Center / Available plugin
  • Cliquer sur le nom du plugin à installer
  • Et cliquez sur le bouton installer
Ajout d'un plugin dans Sonar

Ajout d’un plugin dans Sonar

Il existe un plugin pour de nombreux langage de programmation et outils, ainsi que pour traduire cette interface d’administration.

Une fois le plugin installé il faut relancer le serveur en interrompant la commande du service (étape 1) et en la relançant :

sh {chemin vers sonar}/sonar-3.7.4/bin/{version linux}/sonar.sh console

Lancement de l’analyse

On va se placer à la racine du repertoire du projet, là où se trouve le fichier de configuration et lancer SonarQube-Runner :

sh {chemin de sonarqube-runner}/sonar-runner-2.3/bin/sonar-runner
Lancement de l'analyse avec SonarQube-runner

Lancement de l’analyse avec SonarQube-runner

Résultats

On va se rendre sur l’interface web :

http://localhost:9000

Puis parcourir les projets pour voir le résultat de l’analyse:

SonarQube - Interface du projet

SonarQube – Interface du projet

Conclusion

La mise en place de SonarQube pour l’analyse d’un code-source s’est révélée extrêmement simple et rapide. Mais cette opération basique ne prend pas en compte toutes les possibilité de SonarQube, il faudra veiller à configurer l’outil à son goût ainsi que les chemins vers les différents rapports de PHPUnit. Naturellement SonarQube bénéficie d’une bonne documentation pour cela.

Note

Pour cette démonstration nous avons utilisée la version open-source communautaire mais il existe d’autres versions à destination des entreprises.

Démo de SonarQube

Pour trouver rapidement une configuration pour votre projet n’hésitez pas à chercher dans ce projet.

La revue de code : brouillon d’idées

La revue de code est un processus visant à améliorer de manière continue la qualité du code produit par une équipe de développement. Cette pratique est tout aussi importante que les tests unitaires mais pourtant, à ma connaissance, moins d’outils existent pour aider à cette revue. Et sans bon outil, simple et pratique à utiliser, on ne permet pas son adoption.

Le seul outil que j’ai rencontré est l’interface de BitBucket qui permet d’approuver les commits et éventuellement de commenter une ligne. Une fois approuvé ou commenté, le commit hérite d’une petite icone dans la vue d’ensemble. Il est possible de voir les « Reviewers » du commit, les informations sont visibles mais l’interface reste (selon mon avis très critique) peu adaptée à du code review.

Pourquoi faire de une revue

(liste non exhaustive):

  • voir les développements des autres membres de l’équipe
  • déceler les problèmes de sécurité et de performance
  • faire remarquer les noms de variables non explicites, les fonctions dépréciées, le code en doublons, le refactoring à faire
  • vérifier les tests unitaires, la couverture du code, les cas non traités
  • permettre l’échange de bonne pratiques

Process

Afin de garantir une bonne qualité, le mieux serait que chaque développeur (ainsi que des éventuelles personnes externes) puissent approuver une liste de commit données, y compris son propre travail.

Prototype

Il faudrait une interface simple permettant de visualiser les modifications de ce commit et d’ajouter une question, une remarque ou d’approuver le commit avant de passer au suivant (donc une naviguation simple entre commit suivant/ precedent). Sur cette interface le reviewer devrait pouvoir voir l’ensemble des remarques et avis des autres reviewers.

Prototype de code review

Prototype de code review

A ce moment, la création d’une remarque qui bloquerait le commit (faille de sécurité, refactoring nécessaire, …) entrainerait la création d’un ticket dans un système lié (ou externe de type Mantis, Bugzilla, Jira, …).

Après avoir commenté ou approuvé toute la liste de commit, le reviewer doit pouvoir accéder à une interface listant l’ensemble de ses commits indiquant les remarques ou questions et se chargerait de :

  • répondre aux questions
  • planifier la correction des tickets (liés aux remarques)
Prototype, l'après code-review

Prototype – résultat de ses commits persos

Cette application viserait une revue de code individuelle, car, sur une petite équipe de quatre ou cinq personne la revue pourrait se faire en groupe, autour d’un même écran où les développeur parlerait de leur code à tour de rôle.

Je n’ai pas trouvé trop de ressources sur le sujet mais n’hésitez pas à partager vos méthodes, outils ou logiciels utilisés.