Comment devrais-je me souvenir de ce que je faisais et pourquoi sur un projet il y a trois mois?


72

Je travaillais sur un projet il y a trois mois, puis, tout à coup, un autre projet urgent est apparu et on m'a demandé de déplacer mon attention.

À partir de demain, je reviens à l'ancien projet. Je me rends compte que je ne me souviens pas de ce que je faisais exactement. Je ne sais pas par où commencer.

Comment puis-je documenter un projet de telle sorte que, chaque fois que je regarde en arrière, il ne me faudrait que quelques minutes pour aller de là où je suis parti. Existe-t-il des meilleures pratiques?


98
commentaires et engagement de messages, il y a une raison pour laquelle les gens vous disent de les laisser
ratchet freak

5
Cela ne dépend-il pas vraiment de la manière dont vous avez suivi le projet? Devrions-nous présumer que vous faites tout de la mémoire sans autre documentation?
JeffO

4
@ratchetfreak J'étais sur le point de dire "Ce n'est utile que pour les développeurs" jusqu'à ce que je réalise que vous pouvez appliquer le même principe à n'importe quoi. La plupart des référentiels de documents ont une section de notes ou une description; les livrables par courrier électronique ont des corps de message (souvent ignorés). Les documents peuvent avoir suivi les modifications et les annotations. Il y a aussi tout un écosystème de commentaires et de messages dans le monde de la Premier ministre! </
epiphany

6
J'utilise un système de contrôle de version pour me rappeler ce que j'ai fait la dernière fois et un système de suivi des bogues pour déterminer ce qu'il reste à faire.
Lie Ryan

2
Oh oui, une fois après une pause de trois mois, on m'a demandé lors d'un entretien d'embauche de décrire mon dernier projet. Je l'ai fait, mais quand ils ont demandé des détails, je ne pouvais pas me souvenir d'eux. Ils m'ont refusé parce qu'apparemment, je suis un faux si je ne me souviens pas de ça. Cela s'est passé il y a environ 15 ans, mais je m'en souviens encore.
Andrew Savinykh

Réponses:


35

Je voulais juste donner quelques conseils qui ne seront pas utiles dans votre situation actuelle, mais vous pouvez commencer à les mettre en œuvre maintenant pour vous aider à l'avenir.

Bien sûr, il y a des candidats évidents tels que les listes de tâches et les journaux de problèmes; L'examen des problèmes récemment ajoutés devrait vous donner un indice sur ce que vous faisiez lorsque vous avez été retiré du projet.

Lors de précédents projets sur lesquels j'avais travaillé, les personnes devaient conserver un journal de projet dans le cadre du processus de gestion de la qualité. Le contenu n'était pas très clairement défini, mais l'idée était de garder un journal quotidien des éléments liés au projet pouvant être utiles pour la poursuite des travaux à l'avenir ou pour la révision des activités à terme; par exemple:

  • Observations sur la qualité du projet

    ce code peut utiliser une refactorisation

    fait une mise en œuvre rapide pour que cela fonctionne, mais ABC serait mieux.

  • Tous les éléments / problèmes que vous ne voudriez pas enregistrer officiellement dans un outil de suivi des problèmes

    "devrait faire fonctionner cette méthode x < 0mais c'est actuellement hors de portée.

  • Décisions de conception - en particulier non triviales.

    Notre fonction de tri standard effectue un tri rapide, mais cela ne conserve pas l'ordre des éléments dans la condition de tri, ce dont nous avons besoin ici.

    L'algorithme évident serait ABC mais cela échoue ici car il xpourrait être négatif et nous avons donc besoin de la forme généralisée ( lien Wikipedia ).

  • Problèmes rencontrés et comment vous les avez résolus. Un point très important, de mon point de vue personnel: chaque fois que vous rencontrez un problème, notez-le dans le journal.

    J'ai vérifié le code, mais l'erreur XYZ0123 a été détectée. J'ai d'abord dû mettre à niveau le composant C vers la version 1.2 ou supérieure.

Les deux derniers points sont très importants. J'ai souvent rencontré une situation ou un problème similaire - parfois dans un projet complètement différent - et j'ai pensé "hmm, je me souviens d'avoir passé une journée là-dessus, mais quelle était la solution à nouveau?"

Lorsque vous revenez à un projet après un certain temps, la relecture du journal du projet (que ce soit le vôtre ou celui du dernier développeur) devrait vous ramener dans le flux que vous aviez lorsque vous êtes parti et vous avertir de certains des pièges que vous avez rencontrés. peut sinon tomber à nouveau.


68

Les listes de tâches sont magiques. En règle générale, vous devez conserver une liste de tâches active pour chaque projet et même pendant que vous êtes en train de programmer, si vous pensez que quelque chose doit être fait et que vous ne pouvez pas le faire immédiatement, alors la liste est affichée. Conservez cette liste dans un endroit bien connu, soit dans une feuille de calcul ou un fichier texte dans le dossier du projet, électroniquement, soit dans votre journal de bord.

De même, chaque fois que vous quittez le projet pour la nuit (ou le week-end), prenez un post-it, écrivez la prochaine chose que vous allez faire sur la note et collez-la sur le moniteur. Cela rend plus probable que vous y retourniez rapidement le lendemain matin.

Modifier :

Je devrais mentionner que les listes de tâches (des listes de tâches classées par ordre de priorité, classées par lieu et par projet) constituent un élément clé du livre Getting Things Done , que j’ai trouvé très influent.


22
Et si vous travaillez sur un projet agile avec de petites tâches, l'arriéré devrait être votre liste de tâches principale pour ce projet.
Bart van Ingen Schenau

1
J'ai récemment commencé à faire ce que vous avez mentionné dans le dernier paragraphe et cela m'a énormément aidé à démarrer le matin.
TMH

5
En effet. Toujours stationner en descente. C'est une question d'habitude. Je ne quitte jamais une base de code sans me faire une note dans le code ou dans ma liste de tâches sur ce qu'il faut faire ensuite. Je m'assure également que tout ce que je sais qu'il me reste à faire est dans une tâche, soit dans le source (j'utilise la convention TODO: dans les commentaires que mon IDE peut détecter et présenter sous forme de liste), ou dans ma liste de tâches distincte (I l’un pour tous les projets, mais il est classé et hiérarchisé).
Joeri Sebrechts

3
Les codes TODO dans le code sont excellents, mais vous devez faire preuve de diligence pour les y mettre, même pour les petites choses minimes. Il todoest également utile d’ avoir une cible dans votre fichier makefile.
Blrfl

4
trello.com est un épargnant de vie. Même pour les réunions de l’équipe du lundi Monring où j’ai du mal à me souvenir de ce que j’ai fait la semaine dernière et de ce sur quoi je devrais travailler cette semaine. C'est aussi gratuit.
SimonGates

33

Que faire maintenant?

Maintenant, à partir de demain, je reviens à mon ancien projet et je réalise que je ne me souviens plus de ce que je faisais exactement ni par où commencer!

Je suppose que vous n’avez fait aucune des sections suivantes. Donc, consulter une liste de tâches ne fonctionnera pas.

  1. Bloquer une période de temps. Mettez ceci sur votre calendrier et passez du temps à revoir le projet. Cela peut être la révision de la documentation, du code, des exigences, etc.
  2. Acceptez, il faudra un certain temps pour revenir à la vitesse supérieure. Assurez-vous que toutes les personnes concernées réalisent cela. Assurez- vous de réaliser cela.
  3. Commencez par une petite tâche. Reconstruisez votre confiance en faisant quelque chose de petit. Si vous avez une liste de nouveaux éléments, commencez par les plus petits. Cela non seulement reconstruit votre confiance, mais vous aide également à vous familiariser de nouveau avec le projet.

Comment améliorer cela pour vous-même à l'avenir?

Je souhaite savoir comment documenter le projet de telle sorte que, chaque fois que je regarde en arrière, il ne me faut que quelques minutes pour aller de là où je suis parti!

Tout d'abord, vous devez disposer d'un système permettant de garder une trace de vos tâches. Avez-vous un tel système maintenant? Comment gérez-vous votre projet actuel?

Je pourrais être touché par un bus demain et mon équipe aurait une bonne idée de plus de 90% de mes actions. C'est parce que j'ai un système cohérent pour documenter mes:

  • Tâches immédiates (éléments <1 semaine)
  • "Agréable d'avoir" todos
  • Jalons et tâches à effectuer (où les détails ne sont pas significatifs)
  • Conditions / notes de réunion

De plus, j'utilise un VCS et commente mon code le cas échéant.

Cela fonctionne pour moi et mon équipe puisque je suis le développeur principal. Vous pouvez utiliser une sorte de système de suivi des problèmes pour une équipe. Ou un backlog lorsque vous travaillez avec Agile. Il y a une tonne d'options. Si cela vous intéresse vraiment, consultez Obtention de solutions ou autres méthodologies de gestion de tâches pertinentes, qui existent presque précisément à cause de ce que vous décrivez.

À quoi ça sert?

Les spécificités du système sont moins importantes que le fait qu’il s’agisse d’un système cohérent et que vous l’utilisez . Et que vous l'utilisiez. Et l'utiliser. C'est important. Plus important qu'un bon système parfait que vous n'utilisez pas. Ne faites pas "bien, la plupart de mes travaux sont ici, mais certains sont dans ma tête" ou vous détestez revenir sur un projet.

Assurez-vous également que vos commentaires expliquent le "pourquoi" plutôt que le "quoi" du code. Il est beaucoup plus facile de lire "il s’agit de corriger un bogue avec IE8" et de rappeler ce que fait le code qu’un commentaire expliquant simplement les détails techniques.


@TheIndependentAquarius pas de problème, content que ce soit utile. Cette situation peut être accablante.
enderland

@TheIndependentAquarius probablement parce que les commentaires sont généralement destinés à être plus ou moins post-its / stickies. La façon dont Stack Exchange a configuré les choses pour dire "cette réponse était excellente" est soit un vote positif, soit une réponse acceptée. Les commentaires ici ne sont pas nécessairement destinés à durer.
enderland

Une version beaucoup plus simple de cette liste de tâches consiste à utiliser un système de suivi des problèmes. Il existe de nombreux systèmes gratuits disponibles, et de nombreux fournisseurs Git gratuits intègrent un tel système à leur service (voir: GitHub).
BTownTKD

@BTownTKD Je le dis dans ma réponse :)
enderland

C'est une bonne réponse. ajouté pour mettre l'accent.
BTownTKD

14

À mon avis, "reprendre" un projet de code comporte deux parties:

  1. Déterminer où vous vous êtes arrêté
  2. Se souvenir de ce qu'il vous reste à faire

Je pense que c’est l’une de ces choses qui, je pense, si vous faites le contrôle de version de la bonne façon, ce sera votre "autre cerveau".

Où êtes-vous parti ? Tant que vous commettez du code fréquemment, examinez votre dernier jeu de modifications. Il est fort probable que vous fassiez du jogging. Si ce n’est pas le cas, examinez les quelques dernières, en commençant par les plus anciennes et les relances.

En ce qui concerne ce qu'il vous reste à faire , un arriéré devrait servir cet objectif (ou une liste de tâches à faire, ou quoi que vous vouliez nommer. Principalement des éléments pour l'avenir).

Je ne suis pas un développeur de logiciels à temps plein. Je suis un programmeur qui pirate les nuits et les week-ends. Pour cette raison, lorsque le travail ou d'autres éléments non liés à la programmation sont prioritaires, je peux parfois parcourir des jours et des semaines sans même extraire mon code d'un coup d'œil. Ce qui précède s'est avéré très efficace.


10

Il ne s’agit pas là d’une réponse complète - il y en a déjà plusieurs très bonnes qui mentionnent des choses importantes telles que l’utilisation de votre VCS et de votre logiciel de gestion de projet ", mais plutôt d’un addendum qui ajoute quelques points que je n’ai vus trouve très utile et que j’espère que d’autres le trouveront également.

1. Aucune tâche n'est trop tôt ou trop petite pour écrire

Les gens font généralement des listes TODO pour des choses qu’ils envisagent de faire à l’avenir , mais comme la programmation nécessite de la concentration et que nous pouvons être interrompus à tout moment , j’ai trouvé utile d’écrire même ce que je fais en ce moment, ou ce que je suis sur le point de commencer en quelques secondes . Vous pensez peut - être que vous êtes dans la zone et vous ne pourriez oublier la solution qui vient de vous frapper dans ce aha moment, mais quand votre collègue tombe par votre cube pour vous montrer une photo de son orteil infecté , et vous êtes ne pouvant finalement que se débarrasser de lui en commençant à se ronger le bras , vous souhaiteriez peut-être avoir écrit une note rapide, même si ce n'est que sur une note Post-It ™.

Bien sûr, un autre support plus persistant pourrait être meilleur (j'aime particulièrement OmniFocus ), mais le but est au moins de l'avoir quelque part , même si vous terminez dans 20 minutes avant de jeter le Post-It ™. Bien que vous découvriez peut-être que ces informations deviennent utiles, vous pouvez mettre des feuilles de temps ou des factures au client, ou lorsque votre patron / client vous demande sur quoi vous avez travaillé et dont vous ne vous souvenez plus. Si vous déposez toutes ces notes dans une boîte, un tiroir ou un dossier, puis lorsqu'une grosse interruption survient - un projet interrompant -, vous pouvez les parcourir et vous souvenir de tout ce que vous avez fait pour obtenir votre code au point de trouvez-le quand vous revenez au projet.

2. Utilisez un tableau blanc à votre bureau pour capturer de grandes idées

J'ai un tableau blanc de 3 "x 4" à côté de mon bureau. Ainsi, lorsque je commence un projet, je peux réfléchir aux solutions à tous les problèmes que je perçois dans un projet. Il peut s'agir de diagrammes architecturaux, de cas d'utilisation, de listes de risques et d'obstacles, ou de tout ce qui vous semble pertinent.

Certaines approches plus formelles exigent que vous génériez des diagrammes et des cas d'utilisation, etc. sous forme de "livrables" dans un format papier ou électronique, mais je trouve que cela peut créer beaucoup de travail supplémentaire et devenir simplement une série de sous-projets qui se terminent. être divorcé de l'objectif réel du projet principal, et fait simplement partie d'un processus formalisé que vous devez faire, mais auquel personne ne prête beaucoup d'attention. Un tableau blanc est la chose la plus simple qui fonctionne réellement, du moins selon mon expérience. Il est aussi persistant que vous le souhaitez (avec une caméra) et surtout, il vous permet d’obtenir vos idées immédiatement.

Je pense mieux avec un crayon à la main, alors j’exprime naturellement mes pensées sur une surface blanche, mais si vous estimez que ce n’est pas le cas, voici quelques questions qui pourraient vous aider à décider ce qui est pertinent. :

  • Si j'étais le développeur principal, sur le point de partir en lune de miel pendant 3 mois pendant que d'autres développeurs terminaient le projet, quelle direction générale voudrais-je leur donner? Quelles idées voudrais-je être sûr de savoir, ou quelles approches voudrais-je m'assurer de suivre? Quelles bibliothèques ou autres solutions utiles voudrais-je être sûr de connaître?
  • Si ce projet était mon idée à un million de dollars, je savais que cela garantirait mon indépendance financière future, mais que je devais subir une intervention chirurgicale cruciale qui m'inciterait à rester invalide pendant 3 mois, qu'est-ce que je souhaiterais que mon futur le projet?

(Lorsque je note mes idées pour la première fois, je ne m'inquiète que de leur donner un sens à mon moi actuel. Une fois qu'elles sont en baisse, je peux les regarder de manière plus critique et faire des changements pour m'assurer qu'elles ont un sens pour moi-même ou pour les autres. ne pas communiquer avec les autres au fur et à mesure que vous les écrivez peut conduire à un blocage des rédacteurs - un esprit encrassé par des objectifs opposés.

Je vous recommande de dépenser de l'argent pour acheter un tableau blanc correct, au moins 3 "x 4", et le suspendre à l'espace où vous travaillez normalement. Un tableau blanc physique présente de nombreux avantages par rapport à tout système virtuel.

  • C'est large. En prenant beaucoup de place, elle fait sentir sa présence, et les plans qui y sont associés donnent l’impression qu’ils font partie de votre espace de travail, vous aidant à vous orienter dans la bonne direction tout le temps.
  • C'est là constamment: vous n'avez pas à lancer une certaine application ou un site Web pour y accéder, et vous ne risquez pas d'oublier comment y accéder, ou d'oublier que c'est là.
  • Il est immédiatement accessible lorsque vous avez une idée à laquelle vous souhaitez réfléchir.

Vous perdez de nombreux avantages si vous utilisez simplement un tableau blanc dans une salle de réunion, puis prenez un instantané avec votre téléphone. Si vous gagnez de l'argent en programmant, cela vaut bien le coût d'un tableau blanc décent.

Si vous avez un autre projet interrompre celui qui a rempli votre tableau blanc, vous devrez peut - être recourir à l'instantané sur votre téléphone, mais au moins vous aurez que dans 3 mois lorsque le projet « urgent » est terminé et vous devez retourner à l'autre. Si vous voulez le recréer sur votre tableau blanc, cela ne vous prendra probablement que 15 minutes et vous constaterez que vous pouvez l’améliorer beaucoup en cours de processus, ce qui rend ce petit investissement de temps très rentable.

3. Sensibiliser les intervenants au coût d’une interruption de projet

Je trouve la métaphore d’un avion utile: commencer et terminer un projet, c’est comme piloter un avion. Si vous renflouez au milieu du vol, l'avion n'attendra pas que vous reveniez, et vous avez besoin d'un moyen de transport pour vous rendre du projet / vol en cours au suivant. En fait, si vous êtes au milieu d’un vol Phoenix-Fargo et qu’on vous dit que vous devez interrompre ce vol pour prendre un autre avion de Denver à Detroit, vous devez atterrir au premier avion à Denver (qui heureusement pas très loin de votre trajectoire de vol - pas toujours le cas avec de vraies interruptions) et quelqu'un doit trouver quoi faire avec la cargaison et les passagers. Ils ne vont pas rester assis et attendre pour toujours.

L’intérêt de ces projets est que la transition d’un projet à l’autre entraîne une lourde dépense de temps et laisse beaucoup de points faibles qu’il faut régler.

Dans un projet, il y a évidemment et inévitablement beaucoup de choses qui se passent dans votre tête pendant que vous travaillez et toutes les pensées ne peuvent pas être sérialisées sur un support écrit, et toutes les iotes de ces pensées qui sont sérialisées ne resteront pas après la désérialisation. Bien que nous puissions partiellement capter nos pensées par écrit, il s’agit bien d’un format avec pertes.

Le problème (à mon sens) est que les chefs de projet et autres hommes d’affaires voient les projets comme une série d’étapes qui peuvent souvent être réorganisées à volonté (sauf s’il existe une dépendance explicite à leur diagramme de Gantt) et qu’elles peuvent être facilement réparties entre les utilisateurs. ou retardé jusqu'à ce que cela soit plus pratique pour l'entreprise.

Tous ceux qui ont déjà programmé savent que les projets logiciels ne peuvent pas être traités comme des blocs Lego et qu’ils se déplacent comme vous le souhaitez. Je trouve que la métaphore du transport aérien donne au moins aux parties prenantes un élément concret auquel elles peuvent penser et qui ne peut manifestement pas être traité comme une série d'étapes disparates à réorganiser sur un coup de tête. Au moins, il est facile de comprendre votre argument selon lequel de telles interruptions ont un coût. Bien sûr, c'est toujours leur décision, mais vous voulez leur faire prendre conscience de cela avant qu'ils n'interrompent un projet pour vous en donner un autre. Ne soyez pas combatif, mais offrez des informations utiles et la perspective utile du développeur, prêt à faire tout ce dont il a besoin de votre part, mais proposez simplement des informations dont il ne serait peut-être pas au courant si vous ne le lui dites pas.


En bref:

  1. Notez tout ce que vous êtes sur le point de faire, même si vous pensez ne pas en avoir besoin par écrit. Même un petit crayon bat une longue mémoire.
  2. Faites un brainstorming sur l’ensemble d’un tableau blanc physique auquel vous avez un accès persistant.
  3. Vous pouvez éviter les interruptions de projet si vous informez les décideurs que de telles interruptions ont un coût, et au moins vous aurez défini les attentes afin qu'ils sachent que le projet prendra un peu plus de temps lorsque vous le reprendrez.

1
Les parties prenantes supposent qu'elles paient un développeur professionnel qui commente et documente le code afin que lui (à un moment ultérieur) ou quelqu'un d'autre (à tout moment) puisse prendre en charge le projet. Bien sûr, leur hypothèse est fausse la plupart du temps.
JeffO

Et vous devriez commenter et documenter! J'espère que vous ne pensiez pas que je suggérais le contraire. (Et au fait, je suis d'accord avec votre commentaire.)
iconoclast

2

Vous pouvez consulter l'historique du projet dans votre logiciel de contrôle de version d'il y a trois mois. Lisez vos messages de commit et les diffs les plus récents pour avoir une idée de ce sur quoi vous travailliez.


Je suis surpris que cette réponse n'ait pas été votée. Le journal de contrôle de version est un excellent moyen de savoir où se trouvait quelqu'un il y a plusieurs mois lorsque le projet a été suspendu temporairement. Effacer les messages de journal aide beaucoup. Les diffs et les listes de fichiers modifiés sont un moyen supplémentaire d’obtenir une image de ce qui se passait avant la suspension du projet. Enfin, il y a davantage de développeurs qui utilisent un contrôle de version par rapport au nombre de développeurs qui utilisent un système de suivi des bogues (ou même une simple liste de tâches à effectuer), ce qui rend cette réponse intéressante pour plus de gens, par rapport à la réponse hautement votée de Scott. Whitlock.
Arseni Mourzenko

2

L'utilisation d'un système de contrôle des sources avec des stratégies de ramification et de fusion appropriées, associée à un système de suivi des problèmes (comme Redmine ou GitHub ), vous aide à compartimenter les modifications que vous avez apportées, à les orienter et à documenter le "contexte" manquant. une partie naturelle du flux de travail.

  1. Avant de commencer un changement de code, assurez-vous qu'un "problème" a été enregistré dans votre système de suivi des problèmes. Cela couvre la partie manquante de votre travail intitulée "Qu'est-ce que je faisais?".
  2. Créez une branche dans votre système de contrôle de code source et assurez-vous que vos modifications dans cette branche sont UNIQUEMENT liées au problème susmentionné. Cela vous aidera à isoler les changements et à vous en donner l'historique, en répondant à la question "Où est-ce que je suis parti?" une fois que vous revenez au travail plus tard.
  3. Une fois la modification effectuée, fusionnez-la dans votre coffre et fermez le problème.

1

Il y a beaucoup de réponses longues. Voici un résumé de ce qui m'aide le plus:

  • Code propre.
  • Code propre.
  • Code propre.
  • Contrôle de version (diffs et commit commentaires).
  • Un post-it, une liste de tâches ou un tableau kanban (voir par exemple Trello et Evernote)

Toutefois, les différences, les commentaires de validation, les post-it, les listes de tâches ou les panneaux kanban peuvent être mal interprétés au fil du temps en raison de l'absence de contexte. Alors voici la chose la plus importante:

CLEAN CODE.


De quelle manière exactement code propre code propre code propre aide-t-il avec " Comment dois-je me souvenir de ce que je faisais et pourquoi sur un projet il y a trois mois? " Et la récupération du contexte oublié? Architecture propre architecture propre architecture propre ne serait-il pas utile? On ne plonge généralement pas dans les détails en premier. Il s'agit d'obtenir une vue d'ensemble avant d'examiner les détails. L'oncle omniprésent ne vous aidera pas, malheureusement. Néanmoins, je suis absolument d'accord avec les deux autres points.
JensG

@JensG: Le code est l'architecture. Dans un programme bien écrit, je peux voir le haut de l'architecture de programme en fonction main, ce qui pour un programme de taille significative sera plutôt abstrait. Je peux ensuite plonger plus profondément et voir l'architecture du nettoyage du programme, par exemple. De plus, code propre signifie que fonctions / variables / etc. avoir des noms qui ont un sens et faire une déclaration sur leur signification. Si, au lieu de cela, j'écris Spaghetti / Write-Only-code, je me réveillerai souvent le lendemain matin / mois / année, je regarderai mon code et la seule pensée sera wtf-did-i-do-there. C'est pareil quand ..
phresnel

... lire ou écrire un livre: S'agit-il d'un charabia avec un indice de lisibilité de Flesch-Kincaid de 10, avec des phrases énormes, beaucoup de constructions de mots compliquées, laissant le lecteur se concentrer sur la syntaxe plutôt que sur la sémantique, ou est-il facile à lire avec un indice d'environ 80, et donc ne pas être dans la voie de l'histoire elle-même.
phresnel

Bien que je voie (et ne doute en aucun cas) de la valeur du code propre, je suis fortement en désaccord avec le code étant l'architecture. Le code peut être parfaitement propre et lisible selon toutes les normes, mais toujours écrit de manière à ne pas avoir une vue d'ensemble. Ensuite, la question était de savoir " comment me rappeler ce que je faisais " et " Je ne sais pas par où commencer ". Je ne vois aucune intersection entre l' état actuel du code (propre) et ce que recherche le PO: le point de cheminement exact dans le processus qui mène de l'idée au produit.
JensG

@JensG: Je reconnais votre point. Je pense que nous interprétons simplement "je réalise que je ne me souviens pas de ce que je faisais exactement" différemment. Pour moi, cela ressemblait plus à "je réalise que je ne me souviens pas des algorithmes et des structures de données que j'ai codés et comment je peux les étendre", pour vous, cela ressemblait plus (je suppose) à "je réalise que je ne me souviens pas exactement je voulais mettre en œuvre et la cible de celle-ci ". Langage humain ambigu. ...
phresnel

1

Comment puis-je documenter un projet de telle sorte que, chaque fois que je regarde en arrière, il ne me faudrait que quelques minutes pour aller de là où je suis parti.

Tout d'abord, cela implique que le projet comporte une description de haut niveau et une structure de code que vous pouvez facilement saisir en quelques minutes - par opposition à un zillion de lignes de code sans structure apparente ni commentaires.

Existe-t-il des meilleures pratiques?

Voici les meilleures pratiques que j'ai adoptées au cours d'une carrière de plus de 20 ans dans des projets très petits à très grands et qui m'ont bien servi, moi et mes équipes. Appliquez dans l'ordre indiqué à mesure que votre projet se développe:

  1. Utiliser le contrôle de version, cela vous donne un historique gratuit de ce qui s'est passé, quand et qui a appliqué les modifications. Il vous permet également de revenir facilement à une version antérieure à tout moment.

  2. Modularisez votre code (en fonction du langage et de l'environnement de programmation, utilisez des classes, des modules, des packages, des composants).

  3. Documentez votre code. Cela inclut une documentation récapitulative en haut de chaque fichier (que fait-il? Pourquoi? Comment l’utiliser?) Et des commentaires spécifiques au niveau des fonctions, procédures, classes et méthodes (que fait-il? Arguments et valeurs de retour / types? effets secondaires?).

  4. Ajoutez TODOet FIXMEcommentez pendant que vous codez. Cela vous aidera à vous souvenir des tenants et des aboutissants qui vont inévitablement entrer dans votre base de code et qui vous feront demander plus tard à WTF?! . Par exemple:

    //TODO shall actually compute X and return it
    ... some code that does not compute X yet (maybe returns a fixed value instead)
    
    //FIXME make this constant time instead of n^2 as it is now 
    ... some code that works but is not efficient yet
    
  5. Prenez l'habitude de dessiner des diagrammes pour documenter la structure et le comportement complexe tel que des séquences d'appels entre modules / objets / systèmes , etc. Personnellement , je préfère umlet comme il est rapide à utiliser, crée des graphiques agréables, et surtout ne soit pas dans votre chemin . Mais bien sûr, vous devriez utiliser n’importe quel outil de dessin qui fait le travail. N'oubliez pas que le but de ces dessins est de communiquer de manière succincte, et non de spécifier un système dans les moindres détails (!!).

  6. Ajouter des tests unitaires au début. Les tests unitaires sont non seulement intéressants pour les tests de régression, mais constituent également une forme de documentation d'utilisation pour vos modules.

  7. Ajoutez de la documentation externe au code dès le début. Commencez avec un fichier LISEZMOI décrivant les dépendances requises pour exécuter et développer le projet, comment l’installer, comment l’exécuter.

  8. Prenez l'habitude d' automatiser des tâches répétitives . Par exemple, les cycles de compilation / construction / test doivent être scriptés sous une forme quelconque (par exemple, en utilisation JavaScript grunt, en Python fabric, en Java Maven). Cela vous aidera à vous familiariser rapidement avec votre retour.

  9. Au fur et à mesure que votre projet se développe, ajoutez de la documentation en générant des documents en code source (à l'aide d'une forme de commentaires de style JavaDoc et d'un outil approprié pour générer du HTML ou un PDF à partir de celui-ci).

  10. Si votre projet dépasse un seul composant et comporte un déploiement plus complexe, veillez à ajouter une documentation de conception et d'architecture . Notez à nouveau que le but de ceci est de communiquer la structure et les dépendances plutôt que des détails minutieux.


0

En plus des suggestions sur le suivi de projet, les listes de tâches, Trello, etc., ce que j’ai lu une fois qui aide si vous pratiquez le TDD est de toujours vous éloigner de votre projet avec un nouveau test qui échoue à implémenter chaque fois que vous revenez au projet (demain). , la semaine prochaine ou le mois prochain)

Asseyez-vous, faites des «tests» et reprenez votre chemin.


1
Cela a deux inconvénients. Premièrement, si vous utilisez l'intégration continue, commettre consciemment un test qui échoue est hors de question. Deuxièmement, si vous faites partie d'une équipe de plusieurs personnes, il est possible que d'autres personnes n'apprécient pas si vous commettez un test ayant échoué.
Arseni Mourzenko

1
@MainMa je ​​n'ai pas dit commettre. Juste localement.
Pete

Ma suggestion à tout développeur est de s’engager quand il ne travaillera pas sur un projet, même pendant quelques jours. Des choses arrivent. Votre PC peut être volé ou vous ne pourrez peut-être pas le démarrer demain car le contrôleur RAID a échoué. Vous pouvez quitter le projet et l'autre développeur peut prendre votre place. Vous pouvez être frappé par un bus. Vous pouvez effacer le projet localement parce que cela prend trop de place ou parce que le virus a tué votre système d'exploitation. Donc non, compter sur un code non validé n'est pas une option.
Arseni Mourzenko

1
@MainMa puis valider et pousser vers une branche nommée next-steps. Je ne suis pas sûr de comprendre vos préoccupations au sujet des spécificités de l’approche de contrôle de la révision par rapport au principe de base d’un test qui échoue pour vous aider à relancer votre cerveau lorsque vous revenez à quelque chose. Encore une fois, cela a été proposé en plus des approches standard telles que les arriérés, les listes de
Pete

2
@MainMa: le contrôle de version peut avoir beaucoup en commun avec les sauvegardes, mais ce n'est pas son objectif principal. Si vous avez besoin d'un système de sauvegarde et que vous utilisez le contrôle de version pour qu'il ne remplisse pas cet objectif, procurez-vous une Time Capsule ou quelque chose de similaire. Vous ne devriez jamais être obligé de vous engager prématurément simplement pour forcer votre VCS à servir de sauvegarde. Et vous ne devriez jamais être empêché de faire quelque chose d’autre bénéfique, car vous suivez une politique du type «tout engager immédiatement».
iconoclast

0

En plus des commentaires / listes de tâches / validations, il est important d'être réaliste.

Selon la taille, la complexité et l'état dans lequel vous avez quitté votre travail, le redémarrage d'un projet peut prendre un certain temps. Pour une base de code substantielle composée de nombreux composants en interaction, le temps nécessaire à la mise au point complète peut prendre plusieurs jours.

Bonne vieille patience sera utile.

Lorsque je suis dépassé par mon retour au projet après un certain temps, je sélectionne généralement l'unité de tâche la plus simple et la plus petite et la mets en œuvre. Cela m'empêche de me perdre en essayant de me souvenir de beaucoup de choses à la fois et augmente un peu la confiance en moi. Le plus souvent, je me trouve automatiquement en train de relever des tâches de plus en plus grandes en quelques heures.


0

Je tiens un journal quotidien du travail que je fais. Qu'ai-je fait aujourd'hui, qu'est-ce qui a été difficile aujourd'hui, quelle est la prochaine étape, quelles idées avais-je aujourd'hui pour l'avenir? J'ajoute également un peu de récit sur la journée: y a-t-il eu une conversation ou une réunion intéressante? Quelque chose de colère ou de plaisir? Cela aide à mettre les choses en perspective lorsque je lirai plus tard mon journal.

Lorsque je reviens dans un projet après un certain temps, j'ai lu les dernières entrées du journal pour me familiariser avec le projet. Tous ces petits détails au jour le jour sont extrêmement importants pour nous rappeler le processus de développement. Ils font vraiment une grande différence par rapport à une liste de tâches ou à une documentation de projet classique, car ils vous rappellent à quoi cela ressemble de travailler sur le projet, et pas seulement comment utiliser le produit.


cela ne semble rien offrir de substantiel sur les points soulevés et expliqués dans les 11 réponses précédentes
Gnat

0

Pour moi, la méthode la plus simple pour reprendre des projets consiste simplement à conserver un enregistrement constant des notes relatives à votre travail. Je trouve que le «OneNote» de Microsoft est particulièrement utile pour conserver et regrouper des pages de notes. La barre de recherche facilite en particulier la recherche rapide de vos notes.

Voici certaines choses que je fais dans OneNote pour m'aider à reprendre l'avancement de projets:

  • Journaux quotidiens / hebdomadaires - Conservez un journal quotidien ou hebdomadaire des progrès pour vous aider à comprendre les progrès que vous avez déjà réalisés avec un projet.

  • Liste de tâches - J'ai une liste de tâches générale, mais je conserve également une liste de tâches séparée pour les projets sur lesquels je travaille, afin que je me souvienne de ce que j'ai encore à faire pour un projet. Je laisse parfois aussi // TODO: des éléments de mon code.

  • Notes de projet - Ce que je note incluent des liens vers des éléments de suivi de problème / projet, des extraits de code, des problèmes rencontrés, des décisions prises, des plans et des descriptions de solutions potentielles, une liste des modifications de code, des liens vers le répertoire du référentiel de code, des emails pour le projet et des liens vers documentation du projet.

Ainsi, chaque fois que je reviens sur un projet, je peux ouvrir mes notes et presque instantanément, je peux voir combien de progrès ont été accomplis sur le projet, combien de travail il reste à faire et même voir le train de mes pensées.


-2

Pour des projets simples, je fais ceci:

  1. Un simple fichier README dans le répertoire racine (qui, par conséquent, se retrouvera également dans le contrôle de version) où je note tout ce qui apparaît lors du développement: choses à faire, bugs, améliorations / idées. C’est le premier fichier que je lirais si je devais mettre le projet en veilleuse.
  2. TODO / FIXME / XXX commentaires
  3. J'utilise aussi souvent ToDoList
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.