Jeu Vidéo 2

Commenter un code

Règles de base à 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 brièvement chaque entête de méthode/fonction...
   • Décrire à quoi sert cette fonction
   • Donner des précisions au sujet de ses paramètres ou de la valeur retournée.
4. Ponctuez le reste du code de commentaires opportuns lorsque que vous jugez utile 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.

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 2021, TIM
=======================================
*/
using System.Collections;
using System.Collections.Generic;
using System.Globalization;
using UnityEngine;

/// Classe principale de gestion du
/// projet Tempete de Neige
public class GameManager : MonoBehaviour
{
    // --- Champs --------------------------------------------------------------
	[SerializeField] private GameObject _flocon; // Assigner le prefab dans l'inspecteur

    private GameObject _groupeFlocons;      // GameObject "Dossier" pour contenir tous les 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)

	// S'exécute avant la mise à jour du premier frame
    void Start()
    {
        _groupeFlocons = new GameObject("GroupeFlocons");
        Instantiate(_groupeFlocons);
        nbFlocons = 150; // bon rapport performance vs qualité de l'effet visuel
    }

	// Pour créer les flocons (fonction appelée par un bouton)
	public void CreerFlocons()
	{
		CreerFlocons(nbFlocons);
	}

	// Instancie le nombre de prefab de flocons spécifié en paramètre
    private void CreerFlocons(int nbFlocons)
    {
		// Ce if s'assure qu'il n'y a pas trop de flocons
		if(nbFlocons > _MAX_FLOCONS)
		{
			nbFlocons = _MAX_FLOCONS);
		}

		// Création des flocons
        for (int i = 0; i < nbFlocons; i++)
        {
            GameObject obj = (GameObject)Instantiate(_flocon);
            obj.transform.parent = _groupeFlocons.transform;
			
			// Position aléatoire pour chaque flocon
			obj.transform.position = new Vector2( Rand(9), Rand(4.5) );
        }
    }

	// Retourne un nombre float aléatoire de -nb à +nb
	private float Rand(float nb)
	{
		return Random.Range(-nb, nb);
	}
}

---

OPTIONNEL: Commentaires avancés grâce au XML

Les commentaires XML suivent une syntaxe spéciale incluants 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, on se limite souvent à n'utiliser que ce qui est nécessaire pour commenter les méthodes et les déclarations de classes.

Cela va avoir pour avantage d'afficher des précisions concernant votre propre code de façon dynamique 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 XML particulières...

Exemple de méthode avec commentaire XML:

/// <summary>
/// Fait la somme de 2 entiers
/// </summary>
/// <returns>
/// Le total (entier) des 2 entiers fournis
/// </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;
}

Ces commentaires XML seront reconnus par l'éditeur (exemple Visual Studio) et s'afficheront de façon contextuelle pendant la rédation du code:

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

---