Est-il normal / acceptable d'écrire des notes, des pensées, des algorithmes, des décisions pendant le codage et la maintenance? [fermé]

22

Certaines personnes ont ce problème qu'elles ne peuvent pas penser sans mots. Et noter leurs pensées et décisions est la façon la plus efficace de procéder.

Alors - est-il normal et acceptable que j'écrive mes pensées et mes décisions dans un fichier Notepad ++ pendant le codage?

Parfois, cela devrait être acceptable, par exemple lors de la recréation de documentation technique ou du raisonnement sur des algorithmes plus complexes, mais parfois cela peut être étrange, par exemple lorsque je considère des options de conception et que j'essaie de porter un jugement.

L'impact de cette pratique sur la productivité n'est pas clair. D'un côté - le raisonnement avec les mots intérieurs peut être plus rapide qu'avec les mots écrits. De l'autre côté - des problèmes plus complexes nécessitent l'écriture. De plus, si l'on est coincé avec plus d'options de conception, la sensation est meilleure lorsque la décision est écrite, ce qui augmente le moral.

TomR
la source
5
J'ai tendance à le faire aussi, et je le regrette généralement quand je ne le fais pas. Il est vraiment utile d'avoir quelque chose à regarder en arrière plus tard pour se rappeler pourquoi vous avez fait quelque chose d'une certaine manière, ou pour pouvoir prendre une décision plus tard lorsque vous n'êtes pas au plus profond de lui avec une vision en tunnel. Lorsque j'oublie de noter quelque chose, j'oublie généralement pourquoi, puis je passe plus de temps à revenir sur mes pas.
PseudoPsyche
21
J'ai l'impression que nous manquons une partie du contexte? Cette observation a-t-elle été formulée autour d'une plainte d'efficacité Souvent, la critique s'accompagne de suggestions de causes profondes qui peuvent être pertinentes ou non.
Jim Rush
9
"Commentaires et documentation" doit être écrit dans le code source et conservé. Vos réflexions sur la considération des options de conception peuvent être écrites, mais généralement pas conservées, c'est des choses qui vous aideront rarement plus tard (vous pouvez garder des notes sur les résultats de ce processus de réflexion, si ce n'est pas clair dans le code source lui-même, mais ce n'est pas ce que vous avez demandé). Si vous préférez un formulaire électronique, un crayon et un papier, ou si vous pouvez tout faire dans votre tête, cela ne dépend que de vous, mais vous pouvez vous dire ce qui vous convient le mieux.
Doc Brown
4
... PS: Je préfère généralement le crayon et le papier, ou un tableau blanc pour ce genre de choses, et je pense que je ne deviendrais pas un meilleur programmeur si j'essayais de faire tout cela dans ma tête, bien au contraire.
Doc Brown
7
Pourquoi ne serait-ce pas acceptable? Acceptable pour qui?
Paul D. Waite

Réponses:

62

Non seulement c'est normal, c'est une bonne idée.

Il y a une citation célèbre

"Donnez-moi six heures pour abattre un arbre et je passerai les quatre premiers à affûter la hache".

Prendre le temps d'organiser vos pensées et de planifier votre travail avant de coder est du temps bien utilisé. Mettre ces réflexions sur papier vous donnera le temps de réfléchir à vos plans, de les critiquer et de les organiser d'une manière qui serait très difficile si cela ne se faisait que "dans votre tête".

Dan Pichelman
la source
8
C'est une bonne citation, bien que je retire l'attribution erronée. quoteinvestigator.com/tag/abraham-lincoln
Paul Draper
1
Sûrement une déclaration vraie et une bonne citation, mais à ma connaissance la question a un objectif différent. D'après ce que je comprends, le PO ne doute pas de l'importance de planifier à l'avance. Il demande s'il est plus efficace d'écrire ces pensées / planification, ou simplement de ne les garder que dans sa tête.
Doc Brown
2
Compter une heure d'affûtage est plus que suffisant. Cette tâche aurait dû être estimée à 3 heures maximum, mais le mou a été consacré à une surpréparation inutile. Quelle était encore la morale? ;-)
Steve Jessop
26

Oui, c'est parfaitement acceptable et normal.

La documentation de votre processus décisionnel est souvent utile lors de la révision du code, pour aider à déterminer pourquoi le code a été écrit d'une certaine manière.

Ces notes peuvent être incluses directement dans le code sous forme de commentaires, si elles sont suffisamment courtes. Les commentaires détaillés sont souvent conservés dans le cadre d'un document de conception technique externe.

mcknz
la source
4
Je recommanderais fortement de ne pas inclure de notes sur la prise en compte des options de conception et d'essayer de porter un jugement en tant que commentaires dans le code source, celles-ci ne sont jamais "assez courtes". Seuls les résultats finaux de ce processus de réflexion, mais c'est très différent de ce que le PO demandait.
Doc Brown
3
Je me retrouve souvent dans des discussions sur le thème «pourquoi avons-nous pris cette décision». Il est extrêmement utile de revenir à mes notes de projet quotidiennes pour fournir un contexte, y compris les alternatives dont nous avons discuté. Je pense que je suis en bonne compagnie: selon The Everything Store, Jeff Bezos fait de même.
kdgregory
8
@DocBrown - parfois c'est une bonne idée d'inclure les raisons pour lesquelles vous n'avez pas utilisé d'autres méthodes / algorithmes possibles afin qu'un futur développeur n'essaye pas de remplacer ce que vous avez fait
HorusKol
1
@HorusKol: bien sûr, dans de rares cas, c'est du bon sens trivial. Mais c'est tout à fait différent de "documenter le processus de prise de décision" .
Doc Brown
1
@DocBrown à droite, je ne pense pas que quiconque veuille des pages de notes dans leur code source. :)
mcknz
20

C'est une sacrée bonne idée. Jusqu'à ce qu'il devienne un moyen de tergiverser.

La clé est l'équilibre. Je trouve que je suis plus productif si je ne m'enferme pas, mais capture des idées au fur et à mesure qu'elles se présentent.

Si je meulais à un niveau bas et qu'une idée de haut niveau venait, je la notais et j'y revenais plus tard.

La planification du travail est une bonne idée, mais à moins que vous ne deviez communiquer ou présenter devant un public, les meilleurs outils sont un stylo et une serviette. Capturez l'idée. Ne perdez pas de temps à la rendre jolie.

candied_orange
la source
Markdown est un autre excellent moyen de prendre ces notes. Gardez vos mains sur le clavier, ce qui perturbe le moins le processus de réflexion.
RubberDuck
1
Qu'il s'agisse de lancer un éditeur ou de saisir un stylo et une serviette est la meilleure alternative dépend entièrement de vos compétences personnelles en saisie tactile et en écriture. Pour moi, la meilleure solution est clairement l'éditeur.
cmaster - réintègre monica
9

Dans toute situation professionnelle, ce n'est pas seulement "normal et acceptable", c'est obligatoire. Le cycle de développement typique se compose de deux phases de documentation avant même que tout codage ne commence:

  1. Document d'exigences fonctionnelles: généralement rédigé par des analystes commerciaux, spécifiant les fonctionnalités à mettre en œuvre.

  2. Document de conception détaillée: qui est à peu près ce dont vous parlez, juste plus formel, spécifiant la décomposition fonctionnelle (factorisation) du système, les algorithmes, etc. Certains de mes (très) anciens sont en ligne, par exemple ceci .

Pour une documentation moins formelle, je suis d'accord à 110% avec les remarques précédentes sur les commentaires en ligne. C'est la seule voie à suivre; d'une manière ou d'une autre, tout le reste finit par se perdre. Mais les commentaires en ligne soignés et réfléchis sont une compétence de codage distincte, développée par l'effort et la pratique comme toute autre compétence. Vous pouvez voir certains de mes (très) vieux trucs sur, par exemple ceci . Ce style peut ou non vous plaire. Je recommanderais d'abord de trouver du code bien commenté avec un style que vous aimez, et d'émuler cela dans votre propre code. Après un certain temps, adaptez-le comme bon vous semble.

John Forkosh
la source
4

Un bon endroit pour mettre ce type d'informations est directement dans le message de validation de votre système de contrôle de version (SVN, git, etc.). De cette façon, vous pouvez voir les changements et leur raisonnement au même endroit.

Derek
la source
1
Cela les rend également consultables. Vous pouvez rechercher des messages de validation dans la ligne de commande git et sourcetree, par exemple. Si vous utilisez simplement le bloc-notes, il est très probable que les fichiers ne seront plus jamais ouverts et sont difficiles à rechercher sans connaître un bash étendu et écrire un script qui recherche tous les endroits pertinents.
Espérons que
J'essaie de le faire dans mes déclarations de validation ainsi que dans la demande de bogue ou de fonctionnalité avec des liens vers la validation. Je fais également des commentaires en ligne datés dans le code avec les raisons pour lesquelles j'ai changé le code. Cela aide considérablement dans notre ancienne base de code grinçante où les commentaires sont largement inconnus.
delliottg
Non, c'est autre chose. Les messages de validation doivent décrire ce qui a été fait, pas pourquoi. Le pourquoi va dans la documentation de vos commentaires de code, la documentation d'accompagnement et la résolution du problème tracker. Vous ne pouvez pas mettre cinq pages de notes et de travail de conception dans un message de validation, et vous ne devriez pas non plus le vouloir.
Courses de légèreté avec Monica
C'est génial de le mettre dans le système de contrôle de version. Un meilleur endroit est cependant un fichier texte en clair à l'intérieur. Ceux-ci sont plus faciles à utiliser que les messages de validation.
Thorbjørn Ravn Andersen
2

En plus des autres bonnes réponses, j'ajouterai que j'écris souvent mes réflexions sur ce que j'essaie de faire.

Être très explicite sur l'articulation de ce que j'essaie de faire m'aide à réaliser des présomptions, des hypothèses et / ou des exigences qui ne sont pas nécessairement valables.

Cela fait ensuite allusion à des alternatives, que je peux ensuite mieux analyser chacune à son tour; cette écriture aide à sauver ma place si je pense à autre chose.

Je prends des notes rapides pour explorer le souffle et la profondeur, donc cela fonctionne récursivement, m'aidant à élaborer, naviguer et évaluer un arbre de solutions, sauvegarder, explorer, découvrir, réaliser et décider.

Erik Eidt
la source
1

Écrire tout ce qui peut vous faire gagner du temps aux (nouveaux) membres de l'équipe est du temps à consacrer. Assurez-vous simplement que c'est quelque chose dont quelqu'un pourrait avoir besoin plus tard et ne réfléchissez pas à moins que ce soit un vrai projet à long terme.

Cela ne devrait pas non plus prendre de temps. Si vous passez du temps à réfléchir, vous pouvez écrire vos pensées 1 à 1 (tant qu'elles seront / peuvent être utiles à quelqu'un).

Le vrai problème pourrait être de trop penser à ce que vous écrivez. Ce n'est pas parce que vous écrivez que vous devez adhérer à un format déjà existant ou que vous devez aller jusqu'au bout pour créer une documentation complète.

Si vous avez le choix entre ne rien écrire et simplement écrire des notes non formelles sur un bloc-notes, écrivez simplement des notes non formelles.

Si tout va bien
la source
1

Vous dites: "Certaines personnes ont ce problème qu'elles ne peuvent pas penser sans mots. Et noter leurs pensées et décisions est la façon la plus efficace de procéder."

Si écrire vos pensées et vos décisions est la façon la plus efficace de procéder, pourquoi ne serait-il pas normal et acceptable de procéder de la manière la plus efficace? Vous faites ce qui vous convient le mieux. Ce n'est peut-être pas ce qui fonctionne le mieux pour quelqu'un d'autre. Dans ce cas, vous ne laissez personne vous dire ce qui vous convient le mieux et vous ne lui dites pas ce qui est le mieux pour lui. Chacun fait ce qui est le mieux pour lui.

gnasher729
la source
1

Les humains ne peuvent tenir qu'environ sept «choses» dans leur tête à la fois. C'est la raison pour laquelle les numéros de téléphone à sept chiffres. Pour que les programmeurs travaillent efficacement, ils doivent trouver une sorte de système pour décharger les choses de leur mémoire et les récupérer rapidement plus tard si nécessaire. Prendre des notes est un moyen évident et direct, mais tous ceux qui travaillent sur quelque chose de modérément complexe doivent le faire d'une manière ou d'une autre . Lorsque vous jumelez un programme avec quelqu'un, assurez-vous de rechercher sa méthode.

Le développement piloté par les tests est une méthode courante. Dans cette méthodologie, vous écrivez un test qui échoue, vous écrivez juste assez de code pour réussir ce test, puis vous refactorisez votre code pour le rendre plus joli tout en gardant tous vos tests existants réussis. Cette méthodologie conserve toutes vos "notes" encodées dans les tests. Les gens peuvent travailler très rapidement de cette façon sans avoir l'air de prendre des notes, car ils se concentrent uniquement sur le prochain test.

Une autre façon courante consiste à simplement écrire vos notes dans votre code sous forme de commentaires ou de talons de pseudocode, puis de les remplacer progressivement par la vraie chose. C'est ainsi que j'écris habituellement des algorithmes. Mon premier brouillon n'est qu'une fonction principale avec un pseudocode, puis il se remplit progressivement en niveaux d'abstraction de plus en plus profonds.

Ne vous sentez pas mal à l'idée d'utiliser la méthode qui vous convient, mais essayez de remarquer quelles méthodes vos collègues «efficaces» utilisent. Ils ont les mêmes limitations humaines que vous.

Karl Bielefeldt
la source
1
TDD est un exercice de prise de notes? Je ne pense pas.
Robert Harvey