Logo du site

Jeu Vidéo 3

Techniques d'intégration multimédia

Commenter un code

Règles à suivre pour bien commenter un code C#/Unity
  1. Placez un bloc de commentaires au tout début de chacun de vos fichiers de classe précisant...
    • Le nom de l'auteur
    • La date de rédaction
    • La description brève de son utilité et/ou de ses particularités ou restrictions
  2. Commentez chaque déclaration de variable ou de champ (field).
  3. Commentez chaque entête de méthode/fonction en précisant...
    • Son nom, le type de la valeur retournée par la fonction (si elle retourne une valeur)
    • Le nom, le type et une brève description de chaque paramètre.
    • La description brève de l'utilité de la fonction.
  4. Ponctuez le reste du code de commentaires opportuns lorsque que vous jugez nécessaire de préciser un détail ou de diviser votre code pour le rendre plus lisible.
  5. Assurez-vous que chaque ligne de code ou de commentaire n'est pas trop longue. Un maximum de 80 caractères est recommandé. Cela permet de visionner le code plus aisément dans la majorité des éditeurs de codes (incluant des logiciels aussi simples que WordPad ou NotePad) et cela permet d'imprimer le code au besoin en conservant une mise en page convenable.
Commentaires XML

Les commentaires XML suivent une syntaxe légèrement spéciale et permettent d'inclure des balises dans les commentaires qui seront interprétées par l'éditeur de code (ex: Visual Studio) ou qui serviront à générer une documnentation de code automatiquement dans le futur.

Bien qu'il est possible d'inclure bien des instructions permettant de générer une documentation précise, nous allons nous contenter de n'utiliser que ce qui est nécessaire pour commenter les méthodes et les déclarations de classes en XML. Cela va avoir pour avantage d'afficher des précisions concernant votre propre code lors du codage dans votre éditeur de code.

Remarquez que les lignes de commentaires XML débutent par trois / au lieu de deux. Certaines lignes comportent bien entendu des balises...


Exemple de méthode avec commentaire XML:

/// <summary>
/// Fait la somme de 2 entiers
/// <summary>
/// <returns>
/// Le total des 2 entiers fournis (entier)
/// </returns>
/// <param name="nb1">Premier entier</param>
/// <param name="nb2">Second entier</param>
private int Somme(int nb1, int nb2){
	int total = nb1 + nb2;
	return total;
}

Cela permettra l'affichage de conseils contextuels basés sur vos commentaires dans l'éditeur (exemple avec Visual Studio):

code hint dans VS Code

Pour plus d'informations sur les commentaires XML en C#: Commentaires de documentation XML

Un exemple de code bien commenté

Voici un code complet, commenté selon les règles indiquées dans ce document et faisant aussi usage de la nomenclature correcte pour les identificateurs. Il comporte du code relativement avancé pour ce cours, mais ici votre attention devrait se situer au niveau des commentaires et de l'organisation du code plutôt que sur la logique déployée.

// =======================================
//     Auteur: Bob Binette
//     Automne 2019, TIM
// =======================================

using System.Collections;
using System.Collections.Generic;
using System.Globalization;
using UnityEngine;

/// <summary>
/// Classe principale de gestion du
/// projet Tempete de Neige (cours 1 et 2)
/// </summary>
public class GameManager : MonoBehaviour
{
    // --- Champs --------------------------------------------------------------
	
	[SerializeField] private GameObject _flocon; // Assigner le prefab manuellement

    private GameObject _groupeFlocons;      // "Dossier" pour contenir l'ensemble des flocons
    private const int _MAX_FLOCONS = 200;   // Pas plus de 200 flocons (performances!!!)
    private int _nbFlocons;                 // Nombre de flocons à générer (0 par défaut)

	// --- Initialisation -------------------------------------------------------
	
    /// <summary>
    /// S'exécute avant la mise à jour du premier frame
    /// </summary>
    void Start()
    {
        _groupeFlocons = new GameObject("GroupeFlocons");
        Instantiate(_groupeFlocons);
        nbFlocons = 150;
        CreerFlocons(nbFlocons);
    }
	
	// --- Getter / Setters ------------------------------------------------------
	
    // Getter / Setter de _nbFlocons
    public int nbFlocons
    {
        get { return _nbFlocons; }

        set
        {
            if(value>=0 && value <= _MAX_FLOCONS)
            {
                _nbFlocons = value;
            }
            else
            {
                Debug.Log("Aucun flocon n'a été créé");
            }
        }
    }

	// --- Méthodes privées ------------------------------------------------------
	
    /// <summary>
    /// Instancie le nombre de prefab de flocons désiré
    /// </summary>
    /// <param name="nbFlocons">Le nombre de flocons à créer</param>
    private void CreerFlocons(int nbFlocons)
    {
        for (int i = 0; i < nbFlocons; i++)
        {
            GameObject obj = (GameObject)Instantiate(_flocon);
            obj.transform.parent = _groupeFlocons.transform;
        }
    }

}