Documentation du code d'abord? [fermé]

11

Quelqu'un a-t-il déjà essayé de créer une documentation de code complète avant d'écrire le code? J'y pensais plus tôt parce que je pensais que cela aiderait à écrire une interface concrète et ferait en sorte que votre conception initiale ne soit pas étayée en vous faisant réfléchir sur la façon dont les classes interagissent. Est-ce une bonne idée? Quelqu'un l'a-t-il essayé? Aune

documentation aune
la source
2
Oui. C'est une bonne idée. Les gens le font tout le temps. Qu'est-ce que tu veux savoir de plus?
S.Lott
9
C'est une question subjective. Quelqu'un l'a fait au moins une fois du temps, donc la réponse est forcément oui. Personnellement, je préfère simplement me lancer et faire un prototype en premier, car je redécouvrirai inévitablement une meilleure conception environ 5 fois au cours du processus. Lorsque je m'attaque à quelque chose de complexe, je gratte d'abord quelque chose sur un morceau de papier. Si c'est trivial, j'ai tendance à me lancer. StyleCop m'aide à combler les lacunes plus tard.
Job
2
C'est une excellente idée, sinon vous vous retrouvez avec des fonctionnalités non documentées.
chrisw
8
@ S.Lott, le simple fait qu'il pose le genre de question implique qu'il cherche plus d'informations comme je suis sûr que vous étiez au courant. Mais il semble que vous préfériez faire des commentaires sarcastiques sur les défauts des autres.
Kenneth
2
Ce serait encore mieux si vous écriviez des tests d'acceptation, puis utilisiez TDD pour remplir ces tests d'acceptation;).
Martin Blore

Réponses:

5

Oui.

Cela vous fait réfléchir à ce que votre code est censé faire exactement . L'idée est que vous pouvez commencer avec n'importe quelle partie du code et savoir exactement ce qui doit être fait pour terminer ce module.

Il est également plus facile de réparer quelque chose sur la planche à dessin que dans l'IDE.

Maxpm
la source
12
Plus facile à réparer, oui. Plus facile à remarquer, rarement. Les conceptions semblent toujours bonnes jusqu'à ce que vous tentiez de les mettre en œuvre.
CaffGeek
@Chad C'est vrai. J'ai modifié ma réponse pour refléter cela.
Maxpm
4
Je ne suis pas d'accord. Créer d'abord une documentation complète est bien pire qu'une documentation suffisante pour savoir où aller ensuite. Le changement se produit. Il n'y a aucun moyen de savoir si vous allez dans la bonne direction, et au moment où vous le comprenez, vous êtes loin derrière. Allez avec ce qui fonctionne, améliorez-le et corrigez-le au fur et à mesure, laissez le code être la documentation la plus à jour.
Zachary Scott
4
Bien sûr, dès que vous modifiez votre code pour corriger un bogue ou pour répondre à une nouvelle exigence, votre documentation est obsolète. La documentation en tant que tests exécutables est la voie à suivre!
Johnsyweb
Élaborez des idées (esquisse / contour) au préalable oui, mais ne créez pas de documentation. À moins que vous ne préfériez gaspiller beaucoup d'efforts, car vous gaspillerez beaucoup de l'effort initial lorsque la conception sera mise en pratique. De plus, seules les classes / méthodes publiques ou internes doivent être entièrement documentées (y compris la description complète ainsi que les paramètres). Les trucs locaux privés devraient avoir des lignes simples qui décrivent ce qu'ils font pour référence future, mais quoi que ce soit de plus est un gaspillage, car ils seront inévitablement ignorés lors de la phase de génération de la documentation.
Evan Plaice
10

Il y a deux façons d'y penser:

1) Documentation comme dans les documents Word, Wiki, etc. Par définition, vous ne pouvez pas avoir une documentation de code complète parce que vous n'avez pas de code à documenter. Vous pouvez essayer de documenter la conception de haut niveau, les hypothèses, les interfaces et les contrats en premier.

2) Documentation en tant que tests exécutables. Il existe une école de pensée qui déclare que les tests unitaires exécutables sont la meilleure documentation. Cette école de pensée préconise également ce type de documentation avant d'écrire le code (TDD). En même temps, vous n'écrivez pas tous les tests pour l'ensemble du système dès le début. Vous le décomposez d'abord par cas d'utilisation, puis vous effectuez des tests et du code par cas d'utilisation.

Yuriy Zubarev
la source
2
+1 pour TDD. Absolument une meilleure option que de documenter, alors avoir à modifier des quantités importantes de documentation si le code change.
Ethel Evans
+1 également pour la documentation sous forme de TDD.
sevenseacat
vous POUVEZ avoir une documentation complète du produit avant que le produit existe. Je l'ai fait, j'ai travaillé dans des projets où c'était une exigence. Vous n'aurez pas de captures d'écran, mais vous pouvez avoir tout le reste (y compris les diagrammes Visio représentant l'emplacement des éléments à l'écran).
jwenting
@jwenting J'ai aussi et c'était une collection de diagrammes ainsi que plus de 200 pages de documents Word. Non seulement c'était une perte de temps complète, mais il a fallu 2 mois pour produire et une quantité importante de temps de nos PM pour se mettre à jour constamment à mesure que la conception évoluait pour devenir le produit final. En fait, cela aurait probablement été beaucoup plus rapide avec des maquettes graphiques utilisant Balsalmiq. La prochaine fois que je travaillerai sur un projet où c'est une exigence, je ferai remarquer qu'une autre personne devrait être affectée à la gestion à plein temps, car c'est l'effort nécessaire pour le maintenir.
Evan Plaice
+1 TDD pour les preuves de base des composants individuels et des diagrammes pour les hypothèses de conception globales (accent sur l'hypothèse car la conception réelle doit être écrite comme la meilleure application pratique et non pas comme une implémentation 1-1 du diagramme, on les appelle des hypothèses pour une raison ). La documentation complète du logiciel de toutes les classes / méthodes / propriétés publiques / internes vient en dernier grâce à un générateur de documentation (toutes les propriétés / retours / remarques doivent être remplis en premier) et tous les trucs privés / locaux reçoivent une ligne pour décrire ce qu'ils font pour référence future (privé / local est ignoré par le générateur).
Evan Plaice
7

Commençant par la documentation est le modèle classique de cascade, et a tous les pièges associés à ce modèle. Globalement, plus vous documentez, plus vous devez mettre à jour lorsque les exigences changent. Un avantage de commencer avec la documentation utilisateur est que vous pourriez obtenir des commentaires (et donc des modifications) plus tôt. Mais l'expérience montre que la plupart des gens ne savent pas faire correspondre mentalement la documentation aux actions. Nous utilisons donc plutôt des prototypes, qui permettent aux gens d'utiliser réellement le logiciel et de donner leur avis de cette façon.

Une variante de la «documentation d'abord» est la programmation alphabétisée . Commencez par écrire une description de ce que le programme fera du point de vue des programmeurs. Continuez à peaufiner cela jusqu'à ce qu'il compile. Voila, un programme alphabétisé.


la source
Exactement! Le changement se produit. La documentation pourrit. Le code est la forme la plus vraie de documentation.
Zachary Scott
3

Personnellement, je trouve préférable d'utiliser des diagrammes (tels que UML) pour faire une modélisation simple pour montrer le flux des choses. C'est beaucoup plus rapide que de documenter les choses avec des mots et si cela est fait correctement, cela peut être tout aussi descriptif. J'hésiterais cependant à faire de la documentation complète parce que personnellement, je n'ai jamais eu de projet sur lequel j'ai travaillé et qui n'a pas changé au cours de sa programmation.

EDIT: Certains documents doivent cependant être rédigés au fur et à mesure. Cela facilite plus tard la documentation complète.

Kenneth
la source
3

Joshua Bloch discute de ce point dans son interview pour le livre "Coders at Work".

Contrairement à des vues plus orthodoxes et académiques, il conseille quelque chose à l'écoute de vos pensées (peut-être l'avez-vous lu vous-même?): Qu'avant d'écrire la documentation, vous devez comprendre ce que vous voulez du système et obtenir une image plus "réelle" " sentiment. À cette fin, il concevrait une partie des interfaces et du code client qui les utilise.

La chose la plus importante est de savoir ce que vous essayez de construire: quel problème vous essayez de résoudre. L'importance de l'analyse des exigences ne peut pas être surestimée. Il y a des gens qui pensent: «Oh, oui, l'analyse des exigences; vous allez chez votre client, vous dites: "De quoi avez-vous besoin?" Il vous le dit, et vous avez terminé. "

Rien ne pouvait être plus loin de la vérité. Non seulement c'est une négociation mais c'est un processus de compréhension. De nombreux clients ne vous diront pas de problème; ils vous diront une solution. Un client peut dire, par exemple, «J'ai besoin que vous ajoutiez la prise en charge des 17 attributs suivants à ce système. Ensuite, vous devez demander: «Pourquoi? Qu'allez-vous faire du système? Comment pensez-vous qu'il évoluera? »» Et ainsi de suite. Vous faites des allers-retours jusqu'à ce que vous compreniez ce que tout le client a vraiment besoin de faire. Ce sont les cas d'utilisation.

Créer un bon ensemble de cas d'utilisation est la chose la plus importante que vous puissiez faire à ce stade. Une fois que vous avez cela, vous disposez d'un point de référence par rapport auquel vous pouvez mesurer toute solution possible. Ce n'est pas grave si vous passez beaucoup de temps à le rapprocher raisonnablement de la droite, car si vous vous trompez, vous êtes déjà mort. Le reste du processus sera un exercice futile.

La pire chose que vous puissiez faire - et j'ai vu cela se produire - est d'amener un groupe de gars intelligents dans une pièce pour travailler pendant six mois et écrire une spécification de système de 247 pages avant qu'ils ne comprennent vraiment de quoi il s'agit. essayer de construire. Parce qu'après six mois, ils auront un système spécifié très précisément qui pourrait bien être inutile. Et souvent, ils disent: «Nous avons tellement investi dans les spécifications que nous devons les construire.» Ils construisent donc le système inutile et il ne s'utilise jamais. Et c'est horrible. Si vous n'avez pas de cas d'utilisation, vous construisez la chose et ensuite vous essayez de faire quelque chose de très simple et vous vous rendez compte: «Oh mon Dieu, faire quelque chose de très simple comme prendre un document XML et l'imprimer nécessite des pages sur des pages de passe-partout code." Et c'est une chose horrible.

- Joshua Bloch, extrait d'une interview dans " Coders at Work: Reflections on the Craft of Programming " de Peter Seibel

Si vous pensez déjà dans ce sens, il serait bon que vous puissiez vous procurer le livre et lire l'intégralité de l'interview. Comme je l'ai dit, il est toujours très éclairant.

DPM
la source
C'est un bon conseil, mais une bonne documentation inclut l'utilisation de l'API.
Frank Hileman
Pour mémoire, bien que j'apprécie le montage, je pense que cette citation n'est peut-être pas celle à laquelle je pensais. Il semble tangentiellement lié et de plus haut niveau ou lié à la phase des exigences. Je pense qu'il a dit qu'avant d'écrire de la documentation, il commencerait à coder, à écrire du code client qui utiliserait l'interface afin d'avoir une idée approximative de la bonne interface et que (c'est la partie contre-intuitive à mon avis) qui devrait venir en premier, avant d'écrire tout document de conception de bas niveau. Bien sûr, c'est ma faute de ne pas avoir trouvé la citation quand j'ai écrit cette réponse.
DPM
1

La première écriture de la documentation complète du code est probablement exagérée et rappelle quelque peu la méthodologie de la cascade. Cependant, j'ai constaté qu'une approche plus pragmatique consiste à rédiger le fichier README en premier. Voici pourquoi:

Le fichier README ne documente pas tous les détails de votre projet. Au lieu de cela, il contient généralement les informations suivantes:

  1. Description : court "argumentaire de vente". Dites au lecteur pourquoi il devrait continuer à lire.
  2. Exemples rapides : extraits de code court ou captures d'écran pour prendre en charge la description.
  3. Démarrage rapide : comment démarrer, instructions d'installation et autres exemples.
  4. Documentation supplémentaire : liens vers la documentation complète et plus d'informations.
  5. Organisation du projet : qui sont les auteurs, comment contribuer, comment déposer les bugs.
  6. Mentions légales : licence, droit d'auteur et tout autre détail juridique.

Écrire le "argumentaire de vente" à l'avance me force à être clair sur pourquoi ce projet devrait exister et pourquoi les développeurs devraient l'utiliser. Le simple fait d'écrire des phrases complètes pour décrire le projet le change souvent pour le mieux: vous le comprenez mieux, développez de nouvelles idées et découvrez des problèmes potentiels. C'est aussi un excellent outil de priorisation: tout ce qui se trouve dans le «pitch de vente» est un incontournable!

Les «exemples rapides» et le «guide de démarrage rapide» m'obligent à réfléchir aux principaux cas d'utilisation du point de vue de l'utilisateur. J'ai trouvé que faire cela avant d'écrire du code - avant d'être embourbé dans les détails d'implémentation et les délais serrés - conduit à des API et des conceptions beaucoup plus propres. N'oubliez pas: les programmes doivent être écrits pour que les gens puissent les lire, et accessoirement pour les machines à exécuter ( SICP ).

Dans "documentation supplémentaire", je crée un aperçu des pièces qui auront besoin d'une documentation détaillée, à faire plus tard. «L'organisation du projet» me permet de savoir qui va travailler sur le projet et les pratiques de codage. Les "mentions légales" ... eh bien, peuvent aussi bien les supprimer.

Une fois ce README de base en place, vous disposez d'un document utile pour la discussion, les revues de conception, la répartition du travail et la planification du projet. Lorsque vous travaillez sur le projet, revenez fréquemment avec le fichier README pour vous assurer que vous êtes toujours sur la bonne voie. De plus, la mise à jour incrémentielle du fichier LISEZMOI et de la «documentation supplémentaire» au fur et à mesure signifie que toute votre documentation sera effectuée lorsque le code sera terminé, ce qui est une expérience beaucoup plus agréable que d'avoir à se précipiter pour tout documenter à la dernière minute.

Pour plus d'informations, consultez les informations suivantes:

  1. Développement piloté par le fichier Lisezmoi
  2. Le code le plus important n'est pas le code
  3. Vous êtes ce que vous documentez
Yevgeniy Brikman
la source
0

Pourquoi ne voudriez-vous pas penser à la façon dont les classes interagissent? Pourquoi est-ce une mauvaise chose? En fait, je pense aux interactions avant même de savoir quelles sont les classes. De cette façon, les classes s'identifient.

Tremper
la source
0

Vous devez avoir une idée de ce que vous prévoyez de faire avant d'écrire le code. Le problème est toujours de savoir comment synchroniser ce que vous avez codé avec ce que vous avez écrit? Certains disent de ne pas essayer, d'autres disent d'oublier les documents initiaux et de maintenir les commentaires. Bien sûr, le code est toujours la source canonique. La question devient alors de savoir s'il vaut la peine de documenter ce que le code fait pour ceux qui viendront plus tard ou utiliseront le code. N'importe qui peut comprendre ce que fait une fonction. Le travail de l'écrivain est d'aider quelqu'un à comprendre en 5 minutes ce que n'importe qui peut comprendre en une heure. Additionnez les deltas et déterminez votre chemin.

SnoopDougieDoug
la source