EnglishCommencer

Documentation

Commenter et documenter son code : le commentaire qui apporte quelque chose ou qui paraphrase, l'en-tête d'une fonction (rôle, paramètres, valeur renvoyée, préconditions) et la documentation qui reste d'accord avec le code.

  • 27 cartes
  • 5 thèmes
  • Gratuit
Réviser ce deck

Le programme, thème par thème

Le poids de chaque thème suit celui que lui donne l'examen.

  1. Notions
  2. Questions
  3. Ranger et relier
  4. Mises en situation
  5. Comprendre

Quelques cartes du deck

  • Commentaire : de quoi s'agit-il ?

    Voir la réponse

    Texte du programme ignoré à l'exécution, écrit pour les lecteurs du code ; en Python, il commence par un dièse et finit avec la ligne.

    Il sert à dire ce que le code ne dit pas : une raison, une hypothèse, une unité. i = i + 1 # ajoute 1 n'apprend rien.

  • Quel commentaire apporte une information que ce code ne donne pas ?

    ```python
    total = total + note * 5
    `

    • # notes sur 20 ramenées sur 100
    • # ajoute note * 5 au total
    • # multiplie la note par 5
    • # met à jour la variable total
    Voir la réponse

    # notes sur 20 ramenées sur 100

    Les trois autres commentaires redisent le code ligne à ligne. Seul le premier donne la raison du 5 : une conversion d'échelle.

  • Un bon commentaire explique le … d'un choix, pas le …, que le code dit déjà.

    Voir la réponse

    Un bon commentaire explique le pourquoi d'un choix, pas le quoi, que le code dit déjà.

    # les notes sont sur 20, on les ramène sur 100 apporte une information que note * 5 seul ne donne pas.

  • Docstring : de quoi s'agit-il ?

    Voir la réponse

    Texte entre triples guillemets placé juste sous la ligne def, que Python garde en mémoire et que l'aide intégrée peut afficher.

    Contrairement à un commentaire, elle est lisible à l'exécution : help(aire) ou aire.__doc__ la renvoie.

  • Tu modifies une fonction : elle renvoie maintenant un entier au lieu d'un flottant. Que fais-tu de son en-tête ?

    • Je le corrige dans la même modification que le code
    • Je le laisse : il décrivait l'intention de départ
    • Je le corrigerai à la fin du projet, avec toute la documentation
    • Je le déplace dans un commentaire à côté du return
    Voir la réponse

    Je le corrige dans la même modification que le code

    Un en-tête qui ne correspond plus au code trompe les appelants. Le moment où l'on change le code est le seul où l'on sait précisément ce qui a changé.

Réviser ce deck