web-dev-qa-db-fra.com

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

Je souhaite 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 en 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.

documentationcode-reviewsdocumentation-generationhelp-documentation
21
Hamed_gibago

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 seront 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 des commentaires a souligné quelque chose de bien - les commentaires excessifs sont généralement effectués lors de l'écriture du 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

Les commentaires minimaux qui expliquent pourquoi et quoi 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é, ouais, 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. _client = login() se connecte-t-il au service de messagerie? OMG!"

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

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

Commentaires en ligne

Une chose que vous devriez PAS (et si je pouvais écrire plus gros, je le ferais), c'est d'écrire vos commentaires dans 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 sur le code, et ils doivent 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 fonction login() et fournir les paramètres à send_mail() avec 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 fonctionne-t-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 futur en codant ;-)

16
Yotam Salmon

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 numberOfItemsFound par 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.
55
Mario

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 n 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 fonctions comme s'il s'agissait de commentaires, par exemple, ne pas utiliser UpdtTbl avec un commentaire expliquant qu'il met à jour la table avec les règles fournies lorsque UpdateTableContentsWithSuppliedRules peut ê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".

Devenez meilleur en lisant le 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. Ainsi, 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.

25
David Arno

Fournir une lettre de motivation

À moins que vous ne soyez dans un domaine très technique, la plupart des questions concernant 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.

Simple extrêmement points 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 élimine les réponses StackOverflow et upvotes de 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
5
Dennis Jaheruddin

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 à réviser, car les changements purement mécaniques peuvent être rapidement survolés, puis écartés.

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

1
Simon Richter

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 métaphores (par exemple appeler un MultiButtSupporter un soda), 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 coupure 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 de soin 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.

1
J.G.