Bien utiliser les commentaires

C'est bien souvent ce que l'on reproche aux débutants, mais tout le monde le sait, débutant ou pas, beaucoup de développeurs ne commentent pas sinon mal leurs codes.

En admettant que vous soyez ici pour changer et commencer à commenter votre code. Comment écrire des commentaires de qualité ?

DRY dans les commentaires

Écrire des commentaires n'est déjà pas super marrant alors, évitez d'en écrire trop, d'écrire les mêmes informations à plusieurs endroits.

Dites-vous qu'un code trop commenté (surtout si vous vous répétez dans vos commentaires) est d'aussi mauvaise qualité qu'un code non commenté. En effet, il deviendra vite rébarbatif et plus personne ne lira vos commentaires ce qui les rend tout à fait inutiles.

Une technique pour ne pas vous répéter dans vos commentaires et les rendre plus efficients est de réserver certaines informations à certains commentaires en fonction de leurs positions dans le code.

4 positions = 4 type de commentaires

Le commentaire de fichier

Ce commentaire est utile pour indiquer l'âge du fichier, son créateur et toutes les autres informations nécessaires au niveau du fichier.

/*
 * Converter.swift
 * EuroConverter
 *
 * Created by Nathanaël Cherrier on 19/06/2016.
 * Copyright © 2016 Nathanaël Cherrier. All rights reserved.
 */


class Converter: NSObject {
    private var _base: String!
    
    init(base: String = "EUR") throws {
        super.init()
        
        try validateCurrency(base)
        _base = base
        
        getExchangeRatesFor(base)
    }
}

Certains IDE automatisent la création et la modification de ces commentaires de fichier. Dans ce cas, les dates, les noms de contributeur et les noms de fichiers seront modifiés lorsque que ce sera nécessaire.

Le commentaire de classe

Le commentaire de classe regroupera les informations concernant la classe :  à quoi elle sert, sa version, sa compatibilité, etc.

/*
 * Permet de convertir des devises
 * 
 * @class Converter
 * @since 3.1
 */
class Converter: NSObject {
    private var _base: String!
    
    init(base: String = "EUR") throws {
        super.init()
        
        try validateCurrency(base)
        _base = base
        
        getExchangeRatesFor(base)
    }
}

Les commentaires de méthodes

Ce sont sûrement les commentaires où vous aurez le plus de choses à écrire. Ils vont permettre à tout développeur utilisant vos classes de comprendre comment s'en servir sans même regarder le code de leurs méthodes.

Si les commentaires de méthodes sont bien écrits, vos collègues vous remercieront donc de leur avoir économisé un temps précieux.

class Converter: NSObject {
    private var _base: String!
    
    /*
     * Initialise la classe avec une devise principale
     * @param base {String} Devise servant de base 
     *.                     pour les taux (paires base/USD, base/EUR...) 
     *
     * @throws {ValidationError} Erreur si une mauvaise devise 
     *                           est donnée en paramètres.
     * @return {void}
     */
    init(base: String = "EUR") throws {
        super.init()
        
        try validateCurrency(base)
        _base = base
        
        getExchangeRatesFor(base)
    }
}

Les commentaires de précision

Ces commentaires sont de dernier niveau. Ils sont écrits au milieu du code pour expliquer un bloc de code complexe ou certains choix (méthodologie, conception...).

class Converter: NSObject {
    private var _base: String!
    
    init(base: String = "EUR") throws {
        super.init()
        
        // On ne catch pas l'erreur ici 
        // On laisse la gestion à l'utilisateur de la classe
        try validateCurrency(base) 
        _base = base
        
        getExchangeRatesFor(base)
    }
}

Si vous avez des questions ou des remarques/conseils, n'hésitez pas à laisser un commentaire plus bas ! Je serais ravis de vous lire. Et si vous aimez l'article, n'oubliez pas de le partager avec vos amis.