/ good practices

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 commentaire) 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 rends tout à fait inutile.

Une technique pour ne pas vous répéter dans vos commentaires et les rendre plus efficient 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écéssaires 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 IDEs 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 chose à écrire. Ils vont permettre à tout développeur utilisant vos classes de comprendre comment s'en servir s'ans même regarder le code de leurs méthodes.

Si les commentaires de méthodes sont bien écrit, 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 écrit 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)
    }
}

Tweetez moi si vous avez des questions ou des remarques.