Comment documenter mon code pour une révision de temps minimum? [fermé]


22

Je veux documenter mon code de telle sorte qu'il y ait un minimum de besoin de lire et de parcourir le code à nouveau des mois plus tard.

Je sais qu'il existe différents types de documentation (en code source et extérieur, diagrammes de séquence, etc.).

Je veux juste savoir quel est un moyen efficace de documenter mon code afin que, lorsque quelques mois plus tard, je veux voir mon code, je passe moins de temps à lire le code et à comprendre le flux de code.


42
La meilleure méthode pour passer moins de temps à lire du code plus tard est d'écrire du code plus clair et plus compréhensible .
Mael


La documentation dépend de la cible. Si vous vous adressez aux développeurs, les commentaires dans le code seront très utiles. Si vous vous adressez à des analystes, des diagrammes de la vue d'ensemble sont également utiles. Si vous vous adressez à un public averti, faites un guide d'utilisation.
Laiv

@Laiv Bien vu un développeur de mon propre code et peut-être d'autres codes de développeurs.
Hamed_gibago

La plus grande chose est de garder le code petit. Si le code nécessaire pour implémenter un élément dans votre système de suivi des problèmes est volumineux, votre équipe devra peut-être apprendre à le décomposer davantage afin que la quantité de code examiné ne soit pas écrasante.
Berin Loritsch

Réponses:


16

Je dois admettre que je ne suis pas d'accord avec certaines des choses que les autres réponses recommandaient, alors je vais jeter mes deux cents;

commentaires

La documentation est extrêmement utile pour les étrangers qui lisent votre code. Habituellement, beaucoup de choses ne sont pas suffisamment verbeuses pour être lues et comprises immédiatement, et vous devez ensuite expliquer ce que vous faites.

Edit : la discussion dans la section commentaire a souligné quelque chose de bien - les commentaires excessifs se font généralement lors de l'écriture de mauvais code.

Commenter votre travail doit être précis et minimal, mais, à mon avis, doit certainement être présent. Au moins un commentaire pour 15 lignes de code. Par exemple, au-dessus des blocs sur le code, ajoutez une ligne sur ce que vous faites:

def login(username: str, password: str, create_session: bool = True):

    # Filter the user we need from the database
    hash = md5(password)
    users = db.table("users", db_entities.USER)
    results = [x for x in users.query(lambda c: c.get("username") == username and c.get("password_hash") == hash)]


    if len(results) == 0:
        return None, None
    else:
        # Create a login session record in the database.
        if create_session:
            sessions = db.table("sessions", db_entities.SESSION)
            ses = sessions.new()
            ses.set("username", username) \
                .set("expiery", 31536000 + time.time())
            sessions.update(ses)
            return results[0], ses
        else:
            return results[0], None

Des commentaires minimaux qui expliquent pourquoi et ce que vous faites sont très utiles tout au long du code. Je ne suis pas d'accord avec la réponse qui dit

Si je tombe sur du code contenant des commentaires, je me prépare au pire: le code est susceptible d'être mauvais, et pour être honnête, les commentaires sont également susceptibles d'être mauvais.

Plusieurs fois, gracieusement, un bon code est documenté. Il est vrai que les mauvais programmeurs voient leur documentation comme "D'accord, mon code est mauvais, ajoutons quelques phrases pour le rendre plus clair".

Oui, et bien que cela se produise souvent, il est également vrai que les bons programmeurs qui écrivent du code propre veulent également s'assurer qu'ils reviennent à leur code et comprennent pourquoi ils veulent que leur fonction se comporte comme ça, ou pourquoi en ont-ils besoin ligne qui semble un peu redondante, etc ...

Oui, des commentaires qui expliquent des choses évidentes, des commentaires qui ne sont pas clairs, des commentaires qui ont juste été rassemblés pour s'assurer que "ce code est documenté, oui, peu importe", sont une odeur de code. Ils rendent la lecture du code plus difficile et irritante. (Ajout d'un exemple ci-dessous)

# Logging into Gmail when the module is imported
_client = login()
def get_client():
    global _client
    return _client

Exemple de clarification: "Pas de merde, Sherlock. Se _client = login()connecte-t-il au service de messagerie? OMG!"

Plus de clarification: la login()méthode n'a aucun rapport avec la login()méthode de l'exemple ci-dessus.

Mais les commentaires qui correspondent aux normes, expliquent le pourquoi et non le comment, et répondent aux bonnes questions , sont très très ( très ) utiles.

Commentaires en ligne

Une chose que vous ne devriez PAS (et si je pouvais écrire plus gros, je le ferais), c'est d'écrire vos commentaires sur la même ligne du code. Cela rend les commentaires très spécifiques à la ligne, ce qui manque complètement l'objectif de commenter votre code.

Par exemple, de mauvais commentaires en ligne:

outer = MIMEText(details["message"]) # Constructing a new MIMEText object
outer["To"] = details["to"] # Setting message recipient
outer["From"] = "xAI No-Reply" # Setting message sender
outer["Subject"] = details["subject"] # Setting message subject
outer.preamble = "You will not see this in a MIME-aware mail reader.\n" # I don't know what I'm doing here, I copied this from SO.
msg = outer.as_string() # Getting the string of the message
_client = details["client"] # Assigning the client
_client.sendmail(SENDER, details["to"], msg) # Sending the mail

Serait beaucoup plus facile à lire et à comprendre ce code sans les commentaires, qui le rendent désordonné et illisible.

Au lieu de cela, les commentaires à l'intérieur de votre code doivent être placés au-dessus des blocs de code et répondre aux questions importantes qui peuvent survenir lors de la lecture du bloc de code.

# Constructing the email object with the values 
# we received from the parameter of send_mail(details)
outer = MIMEText(details["message"])
outer["To"] = details["to"]
outer["From"] = "xAI No-Reply"
outer["Subject"] = details["subject"]
outer.preamble = "You will not see this in a MIME-aware mail reader.\n"
msg = outer.as_string()

# Sending the mail using the global client (obtained using login())
_client = details["client"]
_client.sendmail(SENDER, details["to"], msg)

Beaucoup plus clair, non? Maintenant, vous savez également que vous devez utiliser la login()fonction et fournir les paramètres à send_mail()tout ce que vous avez utilisé. Aide un peu, mais il manque encore une chose.

Documentation fonction

A été largement discuté. Vous devez toujours faire savoir à vos lecteurs en quoi consiste votre fonction, pourquoi et ce qu'elle fait. Comment cela fait-il, cela n'appartient pas à la documentation, mais peut-être aux notes de bas de page de la fonction.

Vous devez décrire clairement ce que vous attendez de vos paramètres et si vous souhaitez qu'ils soient obtenus / créés dans une méthode spécifique. Vous devez déclarer ce que votre fonction doit renvoyer, son utilisation, etc.

Encore une fois, c'est mon opinion et ma méthodologie lors de l'écriture de mon code. Non seulement ceux-là, mais ce ne sont que quelques-unes des choses sur lesquelles je ne suis pas d'accord avec les autres réponses. Oh, et bien sûr, non seulement les commentaires lisent votre code, mais votre code lui-même. Écrivez du code propre, compréhensible et maintenable . Pensez à votre avenir en codant ;-)


5
En désaccord avec un exemple donné - au lieu d'écrire de nombreux commentaires dans une énorme fonction, vous devez le composer à partir de nombreuses fonctions plus petites avec des noms descriptifs, qui agiront comme des commentaires. Sans risque d'être déconnecté de ce que fait réellement le code .
user11153

6
Enfin un peu de raison. Extraire chaque morceau de code qui pourrait utiliser un commentaire dans sa propre fonction, c'est ainsi que vous vous retrouvez avec des milliers de fonctions réparties sur des centaines de fichiers.
user369450

2
Ce deuxième exemple est charmant.
Courses de légèreté avec Monica

7
Les commentaires du deuxième exemple sont beaucoup trop verbeux. Certains d'entre eux (par exemple, "Avons-nous trouvé quelque chose?") Répètent simplement ce que dit le code et seraient mieux supprimés. Pour d'autres, vous pouvez gagner en lisibilité en refactorisant, comme en faisant (stream.is_empty ()) la condition de boucle, ou en déplaçant la vérification des accept_literals à l'extérieur.
Frax

3
@cpburnz, "J'ai dû fouiller dans trop de projets hérités et de bibliothèques tierces sans aucun commentaire de code pour apprécier les commentaires qui expliquent ce qui se passe et pourquoi". exactement mon point depuis le début: les commentaires sont là pour expliquer le code de la merde. Étant donné que la question est "comment écrire du code aussi facile à lire", cette réponse est clairement erronée car elle se concentre sur l'écriture de commentaires pour expliquer le mauvais code, plutôt que d'écrire du bon code en premier lieu.
David Arno

55

OMI, la meilleure documentation est celle dont vous n'avez pas réellement besoin. Je déteste également écrire de la documentation et des commentaires.

Cela étant dit:

  • Choisissez des noms lisibles et parlants. N'utilisez pas n, mais à la place numberOfItemsFoundpar exemple.
  • N'hésitez pas à stocker des parties d'un calcul dans une variable constante plutôt que de tout mettre sur une seule ligne.
  • Déplacez des tâches partielles des branches vers leurs propres fonctions (en ligne), si vous les réutilisez ou si la fonction parent devient longue et fastidieuse à suivre.
  • Soyez plus élaboré et optimisez le code plutôt que la lisibilité là où il est vraiment nécessaire.

19
Voici une bonne métrique pour la documentation (lien obligatoire).
Neil

4
Cela devrait également être sur la liste: expliquez dans le code pourquoi vous faites des choses que vous faites.
t3chb0t


4
numberOfItemsFoundest assez verbeux cependant; trop verbeux est également un problème.
Matthieu M.

6
@MatthieuM., Rarement est un problème "trop ​​verbeux" avec les noms dans le code. Trop laconique ou cryptique est un problème très courant.
David Arno

25

Traitez votre code comme de la documentation

Votre code est votre documentation principale. Il décrit précisément ce que l'application, la bibliothèque ou tout ce qui en résulte fait réellement. En tant que tel, toute tentative d'accélérer la compréhension de ce code doit commencer par le code lui-même.

Il y a beaucoup écrit sur la façon d'écrire du code lisible, mais certains des points clés sont:

  • ne vous fiez pas aux commentaires pour expliquer le mauvais code, améliorez le code et supprimez les commentaires,
  • écrire de courtes fonctions, méthodes, classes, etc.,
  • utiliser des noms appropriés au contexte (par exemple, nc'est bon pour une boucle, des noms descriptifs plus longs sont nécessaires pour les éléments avec une plus grande portée),
  • traiter les noms de fonction comme s'ils étaient des commentaires, par exemple ne pas utiliser UpdtTblavec un commentaire expliquant qu'il met à jour le tableau avec les règles fournies lorsqu'il UpdateTableContentsWithSuppliedRulespeut être utilisé comme nom,
  • éviter la mutabilité. Chaque fois que vous modifiez le contenu d'une variable, vous augmentez la complexité du code. Attribuez cette nouvelle valeur à une nouvelle variable (avec un bon nom) lorsque cela est possible.
  • enfin, et surtout, évitez le code "intelligent". Le seul vrai code intelligent est un code facile à lire. Si vous écrivez un bout de code complexe et que vous pensez "wow, ne suis-je pas intelligent ici?", La réponse est presque garantie "non, vous ne l'êtes pas".

Améliorez la lecture du code

La lecture du code, quelle que soit sa simplicité, est une compétence acquise. Personne n'est naturellement bon en lecture de code. Il faut de la pratique; beaucoup de pratique. Donc, par exemple, allez dans Github ou autre et lisez le code des bibliothèques que vous utilisez, plutôt que de simplement utiliser ces bibliothèques. Trouvez le code pour le lire et le lire.

Les commentaires sont une odeur de code

Ce n'est qu'alors que nous arrivons à d'autres types de documentation. Tout d'abord, comme indiqué précédemment, évitez les commentaires. Si je tombe sur du code contenant des commentaires, je me prépare au pire: le code est susceptible d'être mauvais, et pour être honnête, les commentaires sont également susceptibles d'être mauvais. Il est peu probable qu'une personne qui ne peut pas bien communiquer par le biais du code puisse mieux communiquer par le biais du langage naturel.

Méfiez-vous de la documentation API générée automatiquement

Méfiez-vous également de la documentation des API générées automatiquement. Si je dois recourir à la lecture de tels documents, ce sera parce que votre code est si difficile à lire. Encore une fois, rendez le code simple et je peux le lire directement.

Les tests sont aussi des documents

Les tests sont aussi de la documentation. Ne traitez donc pas vos tests unitaires comme une corvée. Traitez-les comme un moyen de communiquer avec les autres (votre auto de six mois plus tard étant inclus ici) quant à la façon dont le code fonctionne et est destiné à être utilisé.

Dessinez des images si cela vous aide

Si vous aimez UML, alors trouvez-vous par tous les moyens un bon outil et générez des diagrammes UML à partir de votre code. N'essayez jamais de l'utiliser pour générer du code. Ce n'est pas bon comme outil de conception et vous vous retrouverez avec un code horrible.

Avoir un document de vue "1000ft"

Enfin, écrivez-vous un document de présentation. Que fait l'application? Comment ça marche? À quels autres systèmes est-il connecté? Des choses comme ça. N'essayez cependant pas de décrire ici la structure du code. Laissez le code faire cela. Laissez ce document vous rappeler pourquoi vous avez écrit le code en premier lieu.


14
Je suis d'accord avec tout votre point, sauf que les commentaires ont leur place. Bien que je convienne qu'il n'y a aucun intérêt à des commentaires comme add 1 to i, les commentaires devraient expliquer pourquoi le code fait ce qu'il fait. Par exemple, le code if (!something.Exists()) {...}peut utiliser un commentaire comme: // something exists only when (explanation of the broader scenario).
Jonathan

16
Nous avons tous vu notre juste part de // increment x x++;commentaires qui ne sont d'aucune utilité, mais il est faux de jeter le bébé avec l'eau du bain et de déclarer que les commentaires sont toujours mauvais. Par exemple, les commentaires du formulaire // this case should never happen because xyz throw exception "unreachable".
angrydust

7
Très belle liste. Mais comme @Jonathan. Je ne suis pas d'accord avec les commentaires. Parfois, cependant, vous devez tenir compte des bogues dans un cadre tiers. Bien que cela puisse être refactorisé dans sa propre fonction, il est toujours agréable de laisser un peu de description des raisons pour lesquelles la solution de contournement (numéro de bug ou nom de bug / description du bug) est requise.
magu_

16
@DavidArno Mais vous ne pouvez pas le faire pour un commentaire expliquant pourquoi quelque chose n'a pas été fait. Comme //XXX: Not using straight-forward method Foo here because .... De tels commentaires peuvent être extrêmement précieux, mais sont impossibles à transmettre avec du code pour des raisons évidentes.
cmaster - réintègre monica

7
Je l'aime encore plus dramatique: chaque commentaire est un échec à bien s'exprimer dans le code . Par exemple, j'ai un commentaire de 4 lignes dans une méthode, expliquant la solution de contournement pour un bogue tiers. Je n'ai pas bien exprimé cela dans le code, c'est donc dans un commentaire . Je dirais que cela améliore la lisibilité, car je doute que quiconque aime faire défiler horizontalement pour lire un nom de méthode très long et très descriptif. "Les commentaires sont une odeur de code" - oui, mais nous devons nous rappeler que tout ce qui sent n'est pas sh * t.
R. Schmitz

5

Fournir une lettre de motivation

Sauf si vous êtes dans un domaine très technique, la plupart des questions sur le code ne porteront pas sur le «comment» mais sur le «pourquoi» ou le «quoi».

En tant que tel, la façon de réduire les gens d'avoir à regarder dans votre code, est d'écrire une courte description de celui-ci. L'avantage de ceci est que vous pouvez compiler un aperçu des descriptions assez facilement, et que c'est beaucoup plus accessible. (Même pour les personnes qui ne veulent pas / ne sont pas autorisées à voir le code).

Même si les gens sont techniques, la lettre d'accompagnement devrait indiquer où ils devraient chercher quelque chose.

Points simples extrêmement minimalistes:

  1. Introduction, pourquoi ce code (base) existe-t-il
  2. Quelle fonction remplit le sous-ensemble de code
  3. Où est le code (nom du script par exemple)

Exemple

  1. Cet ensemble de scripts gratte StackOverflow et les réponses de votes positifs par Dennis Jaheruddin
  2. une. Ce script est chargé d'analyser le html et d'analyser s'il s'agit du bon utilisateur
  3. une. Le script se trouve à: ScrapeAndVote / RecognizeDennis.scr

1

Le gain de vitesse le plus important que j'obtiens généralement en créant des commits séparés qui représentent chacun une étape intermédiaire qui compile et fonctionne.

Donc, si je dois introduire un nouveau paramètre dans une fonction afin d'implémenter une fonctionnalité spécifique, il y a un commit qui ne fait que rajouter le paramètre dans la déclaration, dans la définition et sur tous les sites d'appel. Ensuite, le prochain commit introduit des fonctionnalités et le troisième met à jour les sites d'appels qui utilisent la nouvelle fonctionnalité.

Ceci est facile à examiner, car les changements purement mécaniques peuvent être vus rapidement et ensuite être écartés.

De même, si vous reformatez le code, cela devrait toujours être un commit séparé.


1

Bien qu'il y ait un ou deux points de désaccord apparents entre les réponses existantes, ne serait-ce que dans l'accent, j'essaierai de résumer les conseils habituels d'une manière qui indique clairement d'où tout le monde vient:

  1. Tout d'abord, écrivez du code propre; toute autre "documentation" se chargera d'elle-même par la suite. Le code propre est un ensemble de principes à apprendre en premier lieu: classes à responsabilité unique, méthodes courtes qui font une chose, bons noms de variable et de méthode, meilleurs noms de classe / type que ceux-ci en se concentrant sur les métaphores (par exemple, appelez un MultiButtSupporter a soda), des tests unitaires pour indiquer les exigences, SEC, SOLIDE, un paradigme cohérent et ainsi de suite.
  2. Le code révèle le fonctionnement du code; les commentaires révèlent pourquoi le code fonctionne. Par exemple, expliquez un +1 avec "empêche une erreur de désactivation par 1", ou une formule compliquée avec "dérivée dans ce manuel ou cette page Web".
  3. Quoi que vous ayez fait avec des commentaires, le point 1 ci-dessus peut très bien y parvenir en code propre. Considérez les commentaires comme des échecs / des maux nécessaires, ou même des mensonges si au fil du temps, ils ne sont plus synchronisés avec le code lorsque les deux sont modifiés. Les commentaires ne devraient pas compenser le code mal écrit, car pourquoi les commentaires seraient-ils écrits avec plus de talent ou d'attention que le code?

D'un autre côté, je me trompe probablement trop dans l'autre sens, sans presque jamais utiliser de commentaires. Vos réviseurs de code vous feront savoir si vous avez le solde au mauvais endroit pour eux, mais si vous faites un effort conscient pour suivre le plan en 3 points ci-dessus, vous serez probablement de toute façon proche de leur optimum.


2
En quoi un commentaire "empêche une erreur de désactivation de 1" est-il différent d'un commentaire qui dit "le +1 n'est pas une faute de frappe" ou "je ne suis pas au courant des erreurs de désactivation d'une erreur dans mon programme"? (Les commentaires utiles se rapportent généralement à quelque chose de plus grand que +1 dans le code source, ou à quelque chose en dehors du code source.) Donc, cela laisse toujours "dérivé dans ce manuel ou cette page Web" comme un exemple valide et réellement excellent dans votre point # 2. Ensuite, votre point n ° 3 semble suggérer que vous pourriez être en mesure d'exprimer "dérivé de ce manuel ou de la page Web" en utilisant suffisamment de code propre sans aucun commentaire; wow, j'aimerais voir ça en action.
Jirka Hanika

@JirkaHanika Peut-être que le coup par coup était un mauvais exemple. Quant à 3, je voulais dire "chacun peut" plutôt que "peut-être chacun"; donc non, je ne pense pas que le code seul puisse clarifier de telles choses. (Eh bien, vous pouvez essayer gaussianFromThisTextbookNamesApproximation comme nom de variable, mais c'est une mauvaise idée!)
JG
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.