Exercice - Créer des commentaires de code efficaces

  • 13 minutes

Dans cet exercice, vous allez ajouter des commentaires à votre code et désactiver temporairement certaines lignes de code pour la compilation. Ensuite, vous verrez comment les espaces blancs sont interprétés par le compilateur C# et comment les utiliser pour améliorer la lisibilité de votre code.

Qu’est-ce qu’un commentaire de code ?

Un commentaire de code est une instruction indiquant au compilateur d’ignorer tout ce qui suit les symboles de commentaire de code de la ligne considérée.

// This is a code comment!

Cela peut ne pas sembler utile dans un premier temps, mais ce l’est en fait dans trois cas :

  • Quand vous voulez conserver une note sur l’objectif d’un passage de code. Il peut être utile d’inclure des commentaires dans le code pour décrire la finalité ou le processus de réflexion quand vous écrivez un ensemble particulièrement complexe d’instructions de codage. Vous vous en féliciterez plus tard.
  • Quand vous voulez supprimer temporairement du code de votre application pour essayer une approche différente, mais que vous n’êtes pas encore convaincu que votre nouvelle idée va fonctionner. Vous pouvez placer le code en commentaire, écrire le nouveau code et, une fois que vous êtes convaincu que le nouveau code fonctionnera comme vous le souhaitez, vous pouvez supprimer sans problème l’ancien (le code placé en commentaire).
  • L’ajout d’un message comme TODO vous rappelle qu’il faut examiner plus tard un passage donné du code. Quand les commentaires sont employés de façon judicieuse, ils constituent une approche intéressante. Vous travaillez peut-être sur une autre fonctionnalité quand vous lisez une ligne de code qui a un problème. Au lieu d’ignorer le nouveau problème, vous pouvez le marquer pour l’examiner ultérieurement.

Notes

Les commentaires de code doivent servir à dire ce que le code ne peut pas dire. Souvent, les développeurs mettent à jour leur code, mais ils oublient de mettre à jour les commentaires du code. Il est préférable d’utiliser des commentaires pour des concepts généraux et de ne pas ajouter de commentaires sur le fonctionnement d’une ligne de code individuelle.

Préparer votre environnement de programmation

Ce module comprend des exercices qui vous guident tout au long du processus de création et d’exécution des exemples de code. Si possible, effectuez ces activités en utilisant Visual Studio Code comme environnement de développement. L’utilisation de Visual Studio Code pour ces activités vous permet d’être plus à l’aise dans l’écriture et l’exécution de code dans un environnement de développement qui est utilisé par les professionnels du monde entier.

  1. Ouvrez Visual Studio Code.

    Vous pouvez utiliser le menu Démarrer de Windows (ou une ressource équivalente pour un autre système d’exploitation) pour ouvrir Visual Studio Code.

  2. Dans le menu Fichier Visual Studio Code, sélectionnez Ouvrir le dossier.

  3. Dans la boîte de dialogue Ouvrir le dossier , accédez au dossier Windows Desktop.

    Si vous conservez vos projets de code dans un autre dossier, vous pouvez utiliser cet emplacement à la place. Pour cette formation, l’important est d’avoir un emplacement facile à localiser et à mémoriser.

  4. Dans la boîte de dialogue Ouvrir le dossier , sélectionnez Sélectionner un dossier.

    Si vous voyez une boîte de dialogue de sécurité vous demandant si vous approuvez les auteurs, sélectionnez Oui.

  5. Dans le menu Terminal Visual Studio Code, sélectionnez Nouveau terminal.

    Notez qu’une invite de commandes dans le panneau Terminal affiche le chemin du dossier actif. Par exemple :

    C:\Users\someuser\Desktop>

    Notes

    Si vous travaillez sur votre propre PC plutôt que dans un bac à sable ou un environnement hébergé et que vous avez terminé d’autres modules Microsoft Learn de cette série sur C#, vous avez peut-être déjà créé un dossier de projet pour les exemples de code. Si c’est le cas, vous pouvez passer à l’étape suivante, qui est utilisée pour créer une application console dans le dossier TestProject.

  6. À l’invite de commandes terminal, pour créer une application console dans un dossier spécifié, entrez l’invite suivante :

    dotnet new console -o ./CsharpProjects/TestProject

    Cette commande CLI .NET utilise un modèle de programme .NET pour créer un projet d’application console C# à l’emplacement du dossier spécifié. La commande crée les dossiers CsharpProjects et TestProject automatiquement, et utilise TestProject comme nom pour votre fichier .csproj.

    Si un message s’affiche pour vous indiquer que les fichiers existent déjà, passez aux étapes suivantes. Vous allez réutiliser les fichiers projet existants.

  7. Dans l’affichage EXPLORATEUR, développez le dossier CsharpProjects .

    Vous devez voir le dossier TestProject et deux fichiers, un fichier de programme C# nommé Program.cs et un fichier projet C# nommé TestProject.csproj.

  8. Dans le menu Fichier Visual Studio Code, sélectionnez Ouvrir le dossier.

  9. Dans la boîte de dialogue Ouvrir un dossier , sélectionnez le dossier CsharpProjects , puis sélectionnez Sélectionner un dossier.

  10. Dans l’affichage EXPLORATEUR, développez le dossier TestProject, puis sélectionnez Program.cs.

  11. Supprimez les lignes de code existantes.

    Vous allez utiliser ce projet de console C# pour créer, générer et exécuter des exemples de code au cours de ce module.

  12. Fermez le panneau du Terminal.

Créer et utiliser des commentaires de code

Dans cette tâche, vous allez créer et supprimer différents types de commentaires de code.

  1. Dans le panneau Éditeur Visual Studio Code, entrez le code suivant :

    string firstName = "Bob";
int widgetsSold = 7;
Console.WriteLine($"{firstName} sold {widgetsSold} widgets.");

  2. Pour modifier votre code avec des commentaires et des révisions de code, mettez-le à jour comme suit :

    string firstName = "Bob";
int widgetsPurchased = 7;
// Testing a change to the message.
// int widgetsSold = 7;
// Console.WriteLine($"{firstName} sold {widgetsSold} widgets.");
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");

  3. Prenez une minute pour passer en revue vos commentaires et les mises à jour de code.

    Notez que les commentaires de code sont utilisés pour décrire les modifications potentielles effectuées et pour désactiver temporairement l’ancien message lors du test du nouveau message. L’étape suivante consistera à tester votre code mis à jour. Si le nouveau code vous satisfait, vous pouvez sans problème supprimer l’ancien code qui a été commenté. C’est une approche plus sûre et plus méthodique pour modifier du code opérationnel, jusqu’à ce que vous soyez prêt à le supprimer définitivement.

  4. Dans le menu Fichier Visual Studio Code, cliquez sur Enregistrer.

  5. Dans l’affichage EXPLORATEUR, pour ouvrir un terminal à l’emplacement de votre dossier TestProject, cliquez avec le bouton droit sur TestProject, puis sélectionnez Ouvrir dans le terminal intégré.

  6. À l’invite de commandes terminal, tapez dotnet run , puis appuyez sur Entrée.

    Vous devez normalement voir la sortie suivante.

    Bob purchased 7 widgets.

    Là encore, si vous êtes satisfait de vos modifications, supprimez l’ancien code commenté.

  7. Supprimez les commentaires de code.

    Votre code doit se présenter comme suit :

    string firstName = "Bob";
int widgetsPurchased = 7;
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");

  8. Pour appliquer un bloc de commentaires qui commente plusieurs lignes, mettez à jour votre code comme suit :

    /*
string firstName = "Bob";
int widgetsPurchased = 7;
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");
*/

    Les blocs de commentaires sont utiles si vous devez écrire un long commentaire ou supprimer un grand nombre de lignes de code. Les blocs de commentaires utilisent un /* au début du code et un */ à la fin. L’utilisation d’un bloc de commentaires est le moyen le plus rapide et le plus simple pour désactiver trois lignes de code ou plus.

  9. Remplacez votre code existant par le code ci-dessous :

    Random random = new Random();
string[] orderIDs = new string[5];
// Loop through each blank orderID
for (int i = 0; i < orderIDs.Length; i++)
{
    // Get a random value that equates to ASCII letters A through E
    int prefixValue = random.Next(65, 70);
    // Convert the random value into a char, then a string
    string prefix = Convert.ToChar(prefixValue).ToString();
    // Create a random number, pad with zeroes
    string suffix = random.Next(1, 1000).ToString("000");
    // Combine the prefix and suffix together, then assign to current OrderID
    orderIDs[i] = prefix + suffix;
}
// Print out each orderID
foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

    Notes

    Ce code contient de nombreux concepts C# qui peuvent être nouveaux pour vous. Il n’est pas nécessaire de comprendre ce que fait le code pour apprécier comment les commentaires peuvent aider les lecteurs à comprendre l’objectif du code.

  10. Prenez une minute pour essayer de déterminer la finalité du code.

    À partir des commentaires, vous devez pouvoir déterminer ce que le code fait (en supposant que les commentaires décrivent avec précision l’état actuel et qu’ils ont été mis à jour à mesure que le code a lui-même été mis à jour). Mais pouvez-vous deviner pourquoi ce code existe ? Est-ce que cela ne serait pas utile d’avoir en haut du fichier de code une explication du contexte et de la finalité du code ?

  11. Réfléchissez à la façon dont vous pourriez améliorer les commentaires.

    Notez que ces commentaires présentent deux problèmes principaux :

    • Les commentaires de code expliquent inutilement les fonctionnalités évidentes des lignes de code individuelles. Ils sont considérés comme étant des commentaires de faible qualité, car ils expliquent simplement comment C# ou les méthodes de la bibliothèque de classes .NET fonctionnent. Si le lecteur ne connaît pas bien ces concepts, il peut se renseigner en utilisant learn.microsoft.com ou IntelliSense.
    • Les commentaires de code ne fournissent aucun contexte pour le problème qui est résolu par le code. Ils sont considérés comme étant des commentaires de faible qualité, car le lecteur n’a aucune information sur l’objectif de ce code, en particulier dans son rapport avec le système au sens large.

  12. Supprimez les commentaires existants.

    Votre code doit se présenter comme suit :

    Random random = new Random();
string[] orderIDs = new string[5];

for (int i = 0; i < orderIDs.Length; i++)
{
    int prefixValue = random.Next(65, 70);
    string prefix = Convert.ToChar(prefixValue).ToString();
    string suffix = random.Next(1, 1000).ToString("000");

    orderIDs[i] = prefix + suffix;
}

foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

    Notez que le code est déjà moins encombré.

  13. Pour ajouter un commentaire qui explique la finalité générale de votre code, modifiez votre code comme ceci :

    /*
  The following code creates five random OrderIDs
  to test the fraud detection process.  OrderIDs 
  consist of a letter from A to E, and a three
  digit number. Ex. A123.
*/
Random random = new Random();
string[] orderIDs = new string[5];

for (int i = 0; i < orderIDs.Length; i++)
{
    int prefixValue = random.Next(65, 70);
    string prefix = Convert.ToChar(prefixValue).ToString();
    string suffix = random.Next(1, 1000).ToString("000");

    orderIDs[i] = prefix + suffix;
}

foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

    L’utilité d’un commentaire est subjective. Dans tout ce qui est lié à la lisibilité du code, vous devez faire appel à votre meilleur jugement. Faites ce que vous pensez être le mieux pour améliorer la clarté de votre code.

Récapitulatif

Voici les principaux points à retenir de cet exercice :

  • Utilisez des commentaires de code pour vous laisser à vous-même des remarques parlantes sur le problème que votre code résout.
  • N’utilisez pas des commentaires de code qui expliquent le fonctionnement de C# ou de la bibliothèque de classes .NET.
  • Utilisez des commentaires de code quand vous essayez temporairement des solutions alternatives, jusqu’à ce que vous soyez prêt à valider la nouvelle solution : vous pouvez alors supprimer l’ancien code.
  • Ne faites jamais confiance aux commentaires. Ils peuvent ne pas refléter l’état actuel du code après de nombreuses modifications et mises à jour.