Logo Zéphyrnet

Intelligence de données générative

Code

Commentaires sur le code : comment écrire un code propre et maintenable

Republié par Platon
Republié par Platon

Date :

Vues: 70

Si vous passez un temps raisonnable à programmer, vous êtes sûr de rencontrer commentaires de code. Vous en avez peut-être même écrit vous-même. Ces minuscules morceaux de texte sont intégrés au programme, mais ils sont ignorés par le compilateur ou l'interpréteur. Ils sont destinés aux humains qui travaillent avec le code, et ils ont de nombreuses applications. Ils peuvent même remodeler votre code ou créer automatiquement de la documentation pour d'autres. Vous voulez savoir comment les utiliser correctement ? Alors vous êtes au bon endroit !

Il est temps d'explorer les commentaires, comment les utiliser et aussi comment ne sauraient pour les utiliser.

Ce que vous apprendrez:
En lisant cet article, vous apprendrez :

  • Qu'est-ce qu'un commentaire, les types et comment les utiliser.
  • Où ils ont commencé et où ils sont maintenant.
  • La différence entre les bons et les mauvais commentaires.
  • Applications pratiques du passé et du présent.

À la fin de l'article, vous saurez pourquoi les commentaires de code sont importants, les meilleures pratiques pour rédiger des commentaires efficaces, certains pièges et erreurs courants à éviter et les outils et ressources que vous pouvez utiliser pour optimiser votre processus de commentaire de code, y compris les générateurs de documentation automatisés. , des linters de commentaires et des plateformes de revue de code.

Vous commencerez par un examen approfondi de ce que sont les commentaires de code.

Que sont les commentaires de code ?

Commentaires dans un programme logiciel se trouvent des annotations lisibles par l'homme que les programmeurs ajoutent pour fournir des informations sur ce que fait le code. Les commentaires prennent plusieurs formes, selon le langage de programmation et l'intention du commentaire.

Ils sont classés en deux types : les commentaires de bloc et les commentaires de ligne.

  • Bloquer les commentaires délimitez une région dans le code en utilisant une séquence de caractères au début du commentaire et une autre séquence de caractères à la fin. Par exemple, certains utilisent /* au départ et */ à la fin.
  • Commentaires de ligne utilisez une séquence de caractères pour demander au compilateur de tout ignorer depuis le début du commentaire jusqu'à la fin de la ligne. Par exemple: #, – or //. La façon d'indiquer les commentaires de ligne dépend du langage de programmation que vous utilisez.

Voici un exemple de l'apparence de chaque type de commentaire dans Swift :

struct EventList: View { // CECI EST UN COMMENTAIRE DE LIGNE @EnvironmentObject var userData: UserData @EnvironmentObject var eventData: EventData /* CECI EST UN BLOC COMMENTAIRE @State private var isAddingNewEvent = false @State private var newEvent = Event() */ var corps : une vue { ... } }

Certains langages de programmation ne prennent en charge qu'un seul type de séquence de commentaires, et certains nécessitent des solutions de contournement pour faire fonctionner une séquence. Voici comment certaines langues gèrent les commentaires :

Tableau des séquences de commentaires en plusieurs langues
Tableau des séquences de commentaires en plusieurs langues

Pensez à la façon dont vous utiliseriez une note autocollante. Pour les programmeurs, un commentaire est une note autocollante aux utilisations illimitées.

Les commentaires ont pris plus d'importance au fil du temps à mesure que leurs utilisations se sont étendues et normalisées. Vous découvrirez bon nombre de ces utilisations dans cet article.

Un bref historique du commentaire

Il n'y a pas si longtemps, les ordinateurs n'étaient pas programmés à l'aide d'un écran et d'un clavier. Ils ont été programmés à l'aide de cartes perforées : de petits morceaux de papier rigide avec des trous perforés dans une séquence pour indiquer des instructions pour un ordinateur. Ceux-ci deviendraient des piles géantes qui étaient introduites dans un lecteur, et l'ordinateur exécuterait le programme.

Il était difficile de savoir d'un coup d'œil ce que faisait chaque carte ou jeu de cartes. Pour résoudre ce problème, les programmeurs écrivaient des notes dessus. Ces notes ont été ignorées par le lecteur de la machine car il ne lisait que les trous de la carte. Voici un exemple :

Une carte perforée avec un commentaire écrit dessus

Aujourd'hui, la plupart des commentaires ont le même objectif : aider à comprendre ce que fait le code.

Code sans commentaires

Un dicton courant parmi les programmeurs est : « Un bon code n'a pas besoin d'explication ». C'est vrai dans une certaine mesure, et certains programmeurs n'écrivent pas de commentaires dans leur code.

Mais que se passe-t-il lorsque ce code devient vraiment gros ? Ou intègre-t-il plusieurs règles et logiques métier ? Ou d'autres personnes ont besoin de l'utiliser? Il serait possible de déchiffrer le code non commenté, mais à quel prix en temps et en effort ?

Lorsque nous nous concentrons constamment sur l'écriture de code, nous oublions que quelques mois, voire quelques semaines, après avoir écrit ledit code, une grande partie de la logique a quitté notre mémoire. Pourquoi avons-nous fait certains choix ? Pourquoi avons-nous utilisé certaines conventions. Sans commentaires, nous devrons passer par l'exercice coûteux de déterminer ce que nous pensions.

Les commentaires sont incroyablement utiles et les bons développeurs devraient les utiliser. Cependant, tous les commentaires ne sont pas créés égaux. Voici un aperçu de ce qui rend les commentaires bons, inutiles ou même contre-productifs.

Bons commentaires

Les bons commentaires sont simples et faciles à lire. Ils clarifient ou indiquent un courant de pensée par opposition au fonctionnement du code.

Ils prennent de nombreuses formes, telles que des annotations, des liens et des citations vers des sources, des licences, des drapeaux, des tâches, des commandes, de la documentation, etc.

Commentaires inutiles

Les commentaires sont bons, mais vous n'avez pas besoin de les utiliser partout. Un piège courant consiste à utiliser des commentaires pour décrire ce que fait le code, alors que c'est déjà clair.

Par exemple, si vous avez du code qui itère dans un tableau et incrémente chaque valeur, il n'est pas nécessaire de l'expliquer - cela devrait être évident pour le programmeur qui examine le code. Quoi permettent de garantir que évident, cependant, est why tu fais ça. Et c'est ce qu'un bon commentaire expliquera.

Décrire l'évidence est un piège courant… et les commentaires qui le font ne font que prendre de la place et potentiellement prêter à confusion.

Mauvais commentaires

Les mauvais commentaires sont plus destructeurs qu'inutiles. Ils causent de la confusion, ou pire, tentent d'excuser un code alambiqué ou mal écrit. N'essayez pas d'utiliser les commentaires comme substitut d'un bon code. Par exemple:

var n = 0 // Numéro de ligne

Au lieu de cela, faites :

var numéro de ligne = 0

Abuser des commentaires, comme encombrer le code avec des commentaires TODO, BUG et FIXME, est une mauvaise pratique. La meilleure solution consiste à les résoudre avant de valider le code lorsque vous travaillez en équipe, ou simplement de créer un problème dans un système de billetterie.

Étant donné que les commentaires sont de forme libre, il est utile d'avoir des conventions ou des modèles pour déterminer à quoi un commentaire devrait ressembler, mais le mélange des conventions entre dans la catégorie des mauvais commentaires.

Avez-vous commenté le code pendant le développement ? Ne vous y engagez pas - résolvez le problème et supprimez le commentaire avant de confondre les autres membres de l'équipe.

Au-delà des annotations

Jusqu'à présent, vous avez appris à utiliser les commentaires comme annotations. Cependant, comme les commentaires n'ont pas de format prédéfini, vous pouvez étendre leur utilisation en transformant votre humble annotation de commentaire en un fichier de données ou un document spécialisé. Voici quelques bons exemples.

LICENCE Commentaires

LICENCE est un type de commentaire qui indique les termes et conditions du code. Vous les verrez particulièrement souvent dans le code open-source. Voici un exemple de la licence MIT :

/* LE LOGICIEL EST FOURNI "TEL QUEL", SANS GARANTIE D'AUCUNE SORTE, EXPRESSE OU IMPLICITE, Y COMPRIS, MAIS SANS S'Y LIMITER, LES GARANTIES DE QUALITÉ MARCHANDE, D'ADÉQUATION À UN USAGE PARTICULIER ET D'ABSENCE DE CONTREFAÇON. EN AUCUN CAS, LES AUTEURS OU LES DÉTENTEURS DU COPYRIGHT NE SERONT RESPONSABLES DE TOUTE RÉCLAMATION, DOMMAGE OU AUTRE RESPONSABILITÉ, QUE CE SOIT DANS UNE ACTION CONTRACTUELLE, DÉLICTUELLE OU AUTRE, DÉCOULANT DE, DE OU EN RELATION AVEC LE LOGICIEL OU L'UTILISATION OU D'AUTRES TRANSACTIONS DANS LE LOGICIEL. */

Étant donné que les commentaires sont de forme libre, la façon dont le commentaire est tapé peut prendre plusieurs formes. Voici un exemple d'Apple :

//===--------------------------------------------- ------------------===// // // Ce fichier source fait partie du projet open source Swift // // Copyright (c) 2015-2016 Apple Inc. et les auteurs du projet Swift // Sous licence Apache License v2.0 avec Runtime Library Exception // // Voir http://swift.org/LICENSE.txt pour les informations de licence // Voir http://swift.org/ CONTRIBUTORS.txt pour la liste des auteurs du projet Swift // //===--------------------------------- ------------------------------===//

CODE-OUT TEMPORAIRE Commentaires

Les programmeurs utilisent CODE DE SORTIE TEMPORAIRE commentaire comme outil de débogage. En retirant un bloc ou une ligne de code du processus de compilation, vous pouvez modifier le code qui s'exécute et celui qui ne s'exécute pas. Cette méthode est couramment utilisée lors d'un débogage de processus d'élimination. Par exemple (construction uniquement pour iOS) :

let package = Package( nom : "CommentOut", plates-formes : [ .iOS(.v14), /* .tvOS(.v14), .watchOS(.v7), .macOS(.v11) */ ], produits : [ .library(nom : "CommentOut", cibles : ["CommentOut"]) ], cibles : [ .target(nom : "CommentOut") ] )

Commentaires DÉCORATIFS

A DÉCORATIF or SÉPARATEUR commentaire peut séparer un fichier ou des blocs de code par catégorie ou fonction. Cela aide les utilisateurs à trouver le code plus facilement. Voici un exemple :

/**************************************************** * * Aides à la mise en œuvre Huffman * ******************************************** ******/

LOGIQUE Commentaires

LOGIQUE les commentaires documentent la justification que vous avez choisie lors de la création du code. Cela va au-delà de ce que le code montre, comme "Quelle a été cette valeur assignée?"

Par exemple (de gestionnaire-de-paquets-swift/Sources/Commandes/SwiftRunTool.swift, lignes 287-288):

private func execute(path: String, args: [String]) throws -> Never { #if !os(Windows) // Sur les plates-formes autres que Windows, signal(SIGINT, SIG_IGN) est utilisé pour gérer SIGINT par DispatchSourceSignal, // mais ce processus est sur le point d'être remplacé par exec, donc SIG_IGN doit être remis par défaut. signal(SIGINT, SIG_DFL) #endif try TSCBasic.exec(path: path, args: args) }

Dans ce cas, le execute La fonction contient des instructions conditionnelles de compilation qui incluront ou ignoreront l'appel du signal. Le commentaire contient l'explication de la raison pour laquelle il fait cela.

Formes avancées de commentaires

Les commentaires peuvent contenir du contenu spécialisé, généralement formaté comme le serait un fichier de données : un fichier dans le code. Il peut également s'agir de simples drapeaux, auxquels les outils d'analyse de code source peuvent répondre de différentes manières.

Signaler les commentaires

Drapeau les commentaires sont généralement utilisés par les linters ; ils activent ou désactivent des fonctionnalités. Voici comment SwiftLint désactive les fonctionnalités à l'aide des commentaires de drapeau :

struct GitHubUserInfo: Content { let name: String // swiftlint:disable identifier_name let avatar_url: String ? // swiftlint:enable identifier_name }

Les compilateurs eux-mêmes utilisent également les commentaires de drapeau comme forme de configuration. Dans l'exemple ci-dessous, vous voyez un script Python exécuté en tant que script CLI et au format UTF-8 :

#!/usr/bin/env python3 # -*- codage : UTF-8 -*-

Notes: La première ligne de commentaire dans les scripts a un nom formel : le case. Son but est d'indiquer quel interpréteur le système d'exploitation doit utiliser lorsqu'il exécute le script. Cela commence toujours par un #!.

TÂCHE Commentaires

Les environnements de développement intégrés (IDE), les éditeurs de texte et certains outils CLI sont capables de lire TÂCHE commentaires laissés par les programmeurs dans un format qui indique une action à effectuer par le programmeur à l'avenir, comme TODO :

// TODO : Changer les autorisations du modèle // FIXME : Convertir les chaînes en Enum

GÉNÉRATION DE DOCUMENTS Commentaires

GÉNÉRATION DE DOCUMENTS les commentaires permettent à un outil d'analyser le code source et de générer un document formaté - généralement HTML - que les utilisateurs finaux peuvent utiliser pour parcourir les classes, les méthodes, etc. Voici un exemple de JavaDoc :

/** * @param string la chaîne à convertir * @param type le type pour convertir la chaîne en * @param le type de l'élément * @param la valeur de l'élément */ V convertir(String string, Class taper) { }

D'autres outils peuvent générer une documentation visible par les IDE et présentée à l'utilisateur dans le code. L'un de ces outils est le balisage de documentation (DocC). Ceci est particulièrement utile pour les API qu'Apple utilise avec ses propres bibliothèques. Voici un exemple du projet open-source SwiftGD :

/// Exporte l'image en tant qu'objet `Data` au format raster spécifié. /// /// - Format de paramètre : format raster des données d'image renvoyées (par exemple, au format jpg, png, ...). La valeur par défaut est `.png` /// - Renvoie : les données de l'image /// - Génère : `Erreur` si l'exportation de `self` au format raster spécifié a échoué. public func export(as format: ExportableFormat = .png) throws -> Data { return try format.data(of: internalImage) }

Commentaires CDATA

CDATA les commentaires intègrent des données formatées dans des fichiers XML et XHTML. Vous pouvez utiliser plusieurs types différents avec ces commentaires, tels que des images, du code, XML dans XML, etc. :

John Smith ]]>

De l'article de Wikipédia sur Commentaires sur la programmation informatique, Vous avez la RESSOURCE type d'inclusion de commentaire : "Les logos, diagrammes et organigrammes constitués de constructions d'art ASCII peuvent être insérés dans le code source sous forme de commentaire". Par exemple:

ClientApp (async_run, batch_process) | | V mru.ini (mru_history) ]]>

S'amuser avec les commentaires

Ce n'est pas parce que les commentaires ne sont pas inclus dans une application que vous ne pouvez pas vous amuser avec eux. Des leçons de vie, des blagues, de la poésie, des jeux de tic-tac-toe et quelques plaisanteries entre collègues ont tous fait partie des commentaires de code. Voici un exemple de py_easter_egg_zen.py :

importez ceci # Le Zen de Python, par Tim Peters # Beau vaut mieux que laid. # Explicit vaut mieux qu'implicite. # Simple vaut mieux que complexe. # Complexe vaut mieux que compliqué. # Plat vaut mieux que imbriqué. # Clairsemé vaut mieux que dense. # La lisibilité compte. # Les cas spéciaux ne sont pas assez spéciaux pour enfreindre les règles. # Bien que l'aspect pratique l'emporte sur la pureté. # Les erreurs ne doivent jamais passer en silence. # Sauf si explicitement silencieux. # Face à l'ambiguïté, refusez la tentation de deviner. # Il devrait y avoir une-- et de préférence une seule-- façon évidente de le faire. # Bien que cela ne soit pas évident au début, sauf si vous êtes néerlandais. # Maintenant vaut mieux que jamais. # Bien que jamais soit souvent mieux que *maintenant*. # Si l'implémentation est difficile à expliquer, c'est une mauvaise idée. # Si l'implémentation est facile à expliquer, cela peut être une bonne idée.

Important: Les commentaires sur les œufs de Pâques ne sont pas les bienvenus dans tous les codes sources. Veuillez vous référer à la politique du projet ou du référentiel ou à votre manuel de l'employé avant d'effectuer l'une de ces actions.

Faits marquants

Aujourd'hui, vous avez appris qu'il y a plus dans les commentaires qu'il n'y paraît. Autrefois considérés comme une réflexion après coup, ils sont maintenant reconnus comme un outil de communication inestimable pour la programmation.

  • Ils aident à documenter et à préserver les connaissances pour la maintenance future du code.
  • Il y a des bons et des mauvais commentaires.
  • Les commentaires peuvent aider à créer une documentation automatisée.

Maintenant, il est temps de s'entraîner ! La seule façon de devenir bon dans les commentaires est de se lancer et de les ajouter.

En intégrant les commentaires à votre processus de réflexion sur la programmation, ils ne deviennent plus une étape supplémentaire à effectuer. Voici quelques façons de pratiquer :

  • Documentez vos projets en cours et tenez compte de toutes les normes définies pour le projet ou le référentiel.
  • Utilisez un linter sur tous vos projets pour contrôler votre mise en forme et vos conventions.
  • Trouvez un générateur de documents et publiez votre travail.

Vous pouvez vous entraîner et contribuer tout en soutenant un projet open source qui a besoin d'aide avec des commentaires et de la documentation.

Où aller en partant d'ici?

Si vous souhaitez en savoir plus sur les commentaires, consultez ces articles et ressources. Beaucoup d'entre eux ont été consultés lors de la rédaction de cet article.

Nous espérons que vous avez apprécié ce regard sur les commentaires ! Vous avez des questions, des suggestions ou des conseils à partager ? Rejoignez-nous sur le forum pour cet article. Vous pouvez tous apprendre les uns des autres.

À propos de l’auteur

Roberto Machorro programme professionnellement depuis plus de 25 ans et commente du code depuis aussi longtemps. Il s'est fait le champion de la documentation du code interne, tiers et open source par frustration d'avoir à maintenir un code mal écrit ou de se débattre avec une documentation indisponible. Il a commencé avec des documents de bibliothèque en utilisant HeaderDoc, JavaDoc et profite maintenant de DocC.

spot_img

Dernières informations

spot_img

Copyright @ 2024 Platon Technologies Inc.