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 vais retourner à l'ancien projet. Je me rends compte que je ne me souviens pas exactement de ce que je faisais. 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, cela ne devrait pas me prendre plus de quelques minutes pour aller de là où je suis parti. Existe-t-il des meilleures pratiques?
Je voulais juste apporter quelques conseils qui ne seront pas utiles dans votre situation actuelle, mais vous pouvez commencer à les mettre en œuvre dès maintenant pour vous aider à l'avenir.
Bien sûr, il y a les 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 une idée de ce que vous faisiez lorsque vous avez été retiré du projet.
Sur les projets précédents sur lesquels j'ai travaillé, les gens devaient tenir un journal de projet dans le cadre du processus de gestion de la qualité. Le contenu n'était pas très clairement spécifié, mais l'idée était de tenir un journal quotidien des choses liées au projet qui pourraient être utiles pour la poursuite des travaux à l'avenir ou pour revoir les activités une fois terminées; par exemple:
Observations sur la qualité du projet
ce code peut utiliser une refactorisation
a fait une implémentation rapide pour que cela fonctionne, mais ABC serait mieux.
Todo items/issues que vous ne voudriez pas enregistrer officiellement dans un outil de suivi des problèmes
"devrait faire fonctionner cette méthode pour
x < 0
mais c'est actuellement hors de portée.
Décisions de conception - en particulier les décisions non triviales.
Notre fonction de tri standard effectue un tri rapide, mais cela ne préserve pas l'ordre des éléments égaux dans la condition de tri, dont nous avons besoin ici.
L'algorithme évident serait ABC mais cela échoue ici car
x
pourrait être négatif, 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 très important, à mon avis personnel: chaque fois que vous rencontrez un problème, notez-le dans le journal.
Vérifié le code mais il a donné l'erreur XYZ0123, il s'avère que j'ai d'abord dû mettre à niveau le composant C vers la version 1.2 ou supérieure.
Ces 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 lecture du journal du projet (que ce soit le vôtre ou le dernier développeur) devrait vous remettre dans le flux que vous aviez lorsque vous êtes parti et vous avertir de certains des pièges que vous sinon, vous risquez de retomber.
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 lorsque vous êtes occupé à programmer, si vous pensez à quelque chose qui doit être fait et que vous ne pouvez pas le faire immédiatement, cela figure sur la liste. Gardez cette liste dans un endroit bien connu, soit dans une feuille de calcul ou un fichier texte dans le dossier du projet par voie électronique, ou dans votre journal de bord papier.
De plus, chaque fois que vous quittez le projet pour la nuit (ou le week-end), prenez une note post-it et écrivez la prochaine chose que vous alliez faire sur la note, et collez-la sur le moniteur. Il est donc plus probable que vous y retourniez rapidement le lendemain matin.
Modifier :
Je dois mentionner que les listes de tâches (les listes de tâches priorisées spécifiquement séparées par lieu et projet) sont un élément clé du livre Getting Things Done , que j'ai trouvé très influent.
Maintenant, à partir de demain, je vais retourner à mon ancien projet et je me rends compte que je ne me souviens pas exactement de ce que je faisais et par où commencer!
Je suppose que vous n'avez effectué aucune des sections suivantes. La recherche d'une liste de tâches ne fonctionnera donc pas.
Je souhaite savoir comment documenter le projet de telle sorte que chaque fois que je regarde en arrière, cela ne devrait pas me prendre plus de quelques minutes pour aller de là où je suis parti!
Tout d'abord, vous devez avoir un système pour garder une trace de vos tâches. Avez-vous un tel système maintenant? Comment gérez-vous votre projet actuel?
Je pourrais obtenir frappé par un bus demain et mon équipe aurait une bonne idée de bien plus de 90% de mes actions. C'est parce que j'ai un système cohérent pour documenter mon:
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, lisez la suite Getting Things Done ou d'autres méthodologies de gestion des tâches pertinentes, qui existent presque précisément à cause de ce que vous décrivez.
Les spécificités du système sont moins pertinentes que ce système est cohérent et vous l'utilisez. Et que vous l'utilisez. Et utilisez-le. C'est important. Plus important qu'un système parfait de Nice que vous n'utilisez pas. Ne faites pas "bien la plupart de mon travail est ici, mais certains sont dans ma tête" ou vous vous détesterez de revenir sur un projet.
Assurez-vous également que vos commentaires expliquent "pourquoi" plutôt que "quoi" pour le code. Il est beaucoup plus facile de lire "c'est pour corriger un bogue avec IE8" et de rappeler ce que fait le code qu'un commentaire expliquant simplement les détails techniques.
À mon avis, la "reprise" d'un projet de code comporte deux parties:
C'est 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ù avez-vous arrêté? Tant que vous validez fréquemment du code, consultez votre dernier ensemble de modifications. Cela fera probablement du jogging dans votre esprit. Sinon, regardez les derniers, en commençant par les commits les plus anciens et en rejouant.
Quant à ce qu'il vous reste à faire, un backlog devrait servir à cette fin (ou une liste de tâches, ou tout ce que vous voulez lui donner. Fondamentalement, des éléments pour l'avenir).
Je ne suis pas développeur de logiciels à plein temps. Je suis un programmeur qui pirate les nuits et les week-ends. Pour cette raison, lorsque le travail ou d'autres choses non liées à la programmation ont une priorité plus élevée, parfois je peux passer des jours et des semaines sans même tirer mon code d'un coup d'œil. Ce qui précède s'est révélé assez efficace.
Ce n'est pas destiné à être une réponse complète - il y en a déjà plusieurs très bonnes mentionnant des choses importantes comme la façon d'utiliser votre VCS et votre logiciel de gestion de projet - mais plutôt un addendum ajoutant quelques points que je n'ai pas vus dans d'autres, que j'ai trouver très utile, et que j'espère que d'autres personnes pourraient également trouver utile.
Les gens font généralement des listes TODO pour les choses qu'ils envisagent de faire à l'avenir, mais puisque la programmation nécessite de la concentration, et puisque 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 vais commencer en quelques secondes. Vous pouvez sentir que vous êtes dans la zone et vous ne pouvez pas oublier la solution qui vient de vous frapper à ce moment aha, mais lorsque votre collègue passe par votre cube pour vous montrer une image de son orteil infecté , et vous ne pouvez finalement vous débarrasser de lui en commençant à vous ronger le bras , vous souhaiterez peut-être avoir écrit une note rapide , même si ce n'est que sur une note Post-It ™.
Bien sûr, un autre moyen plus persistant pourrait être meilleur (j'aime particulièrement OmniFocus ), mais le but est de au moins l'avoir quelque part, même si vous 'terminerai en 20 minutes, puis jetez le Post-It ™. Bien que vous puissiez découvrir que ces informations deviennent utiles, mettre des feuilles de temps ou des factures au client, ou lorsque votre patron/client vous demande sur quoi vous avez travaillé et que vous ne vous en souvenez pas. Si vous déposez toutes ces notes dans une boîte ou un tiroir ou un dossier, alors quand une interruption grande frappe - un projet interrompant - alors vous pouvez les parcourir et vous souvenir de beaucoup de choses que vous avez faites pour obtenir votre code au point où vous le trouverez lorsque vous revenez au projet.
J'ai un tableau blanc de 3 "x 4" à côté de mon bureau, donc quand je démarre 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 formalisées vous obligent à générer des diagrammes et des cas d'utilisation et ainsi de suite en tant que "livrables" dans certains formats papier ou électronique, mais je trouve que cela peut créer un beaucoup de travail supplémentaire, et juste devenir une série de sous-projets qui finissent par être dissociés du but réel du projet principal, et juste une partie d'un processus formalisé que vous devez faire mais que personne ne prête beaucoup d'attention. Un tableau blanc est la chose la plus simple qui fonctionne réellement, du moins d'après mon expérience. Il est aussi persistant que vous le souhaitez (avec un appareil photo) et surtout vous permet de mettre vos idées au clair immédiatement.
Je pense mieux avec un stylo à la main, alors me plonger les pensées sur une surface blanche me vient naturellement, mais si vous ne trouvez pas que ce soit le cas pour vous, voici quelques questions qui peuvent vous aider à décider de ce qui est pertinent :
(Lorsque je griffonne 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 apporter des changements pour m'assurer qu'elles ont un sens pour mon futur moi ou pour les autres. à propos de la communication aux autres comme vous les notez au début peut conduire à un blocage des écrivains - un esprit obstrué par des objectifs concurrents. Descendez-le d'abord; vous soucier de la clarté plus tard.)
Je vous recommande de dépenser de l'argent pour acheter un tableau blanc décent, au moins 3 "x 4", et de l'accrocher dans l'espace où vous travaillez normalement. Il existe de nombreux avantages d'un tableau blanc physique sur tout système virtuel.
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, interrompez celui qui a rempli votre tableau blanc, vous devrez peut-être recourir à l'instantané sur votre téléphone, mais au moins vous aurez ça dans 3 mois lorsque le " urgent "le projet est terminé et vous devez retourner à l'autre. Si vous souhaitez le recréer sur votre tableau blanc, cela ne prendrait probablement que 15 minutes, et vous constaterez peut-être que vous pouvez l'améliorer beaucoup dans le processus, ce qui rend ce petit investissement de temps très utile.
Je trouve la métaphore d'un avion utile: démarrer et terminer un projet, c'est comme piloter un avion. Si vous vous renflouez à mi-chemin du vol, l'avion ne restera pas assis là en l'air en attendant que vous y reveniez, et vous avez besoin d'un moyen de voyager du projet/vol en cours au suivant. En fait, si vous êtes au milieu d'un vol de Phoenix à Fargo et qu'on vous dit que vous devez interrompre ce vol pour prendre un autre avion de Denver à Detroit, vous devrez atterrir le premier avion à Denver (qui n'est heureusement pas loin de votre trajectoire de vol - pas toujours le cas avec de vraies interruptions) et quelqu'un doit trouver quoi faire avec le fret et les passagers. Ils ne resteront pas assis et n'attendront pas éternellement.
Le point de cela pour les projets est que la transition d'un projet à un autre entraîne une grande dépense de temps et laisse beaucoup de points perdus qui doivent être traités.
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 pas toutes les pensées peut être sérialisé sur un support écrit, et pas chaque iota de ces pensées qui are sérialisé restera une fois désérialisé. Bien que nous puissions partiellement capturer nos pensées par écrit, il s'agit très bien d'un format avec perte.
Le problème (tel que je le vois) est que les chefs de projet et d'autres hommes d'affaires considèrent les projets comme une série d'étapes qui peuvent souvent être réorganisées à volonté (sauf s'il existe une dépendance explicite sur leur diagramme de Gantt) et peuvent être facilement réparties entre les personnes ou retardé jusqu'à ce que cela soit le plus pratique pour l'entreprise.
Quiconque a fait n'importe quelle programmation sait que les projets logiciels ne peuvent pas être traités comme des blocs Lego pour être déplacés comme vous le souhaitez. Je trouve que la métaphore du transport aérien donne au moins aux parties prenantes quelque chose de concret auquel elles peuvent penser qui ne peut clairement pas être traité comme une série d'étapes disparates à réorganiser sur un coup de tête. Cela rend au moins facile - comprendre votre point de vue qu'il y a un coût à de telles interruptions. Bien sûr, c'est toujours leur décision, mais vous voulez les en informer avant d'interrompre un projet pour vous en donner un autre. Ne soyez pas combatif, mais offrez des informations utiles et le point de vue utile du développeur, prêt à faire tout ce dont il a besoin de votre part, mais simplement à fournir des informations dont il pourrait ne pas être au courant si vous ne le lui dites pas.
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 validation et les diffs les plus récents pour avoir une idée de ce sur quoi vous travailliez.
L'utilisation d'un système de contrôle de source avec des stratégies de branchement et de fusion appropriées, en conjonction avec un système de suivi des problèmes (comme Redmine , ou GitHub ) vous aide à compartimenter les changements que vous avez faites, donnez-leur une direction et documentez votre "contexte" manquant comme une partie naturelle du flux de travail.
Comment puis-je documenter un projet de telle sorte que chaque fois que je regarde en arrière, cela ne devrait pas me prendre plus de quelques minutes pour aller de là où je suis parti.
Tout d'abord, cela implique qu'il existe une description de haut niveau et une structure de code dans le projet que vous pouvez facilement saisir en quelques minutes - par opposition à des millions de lignes de code sans structure apparente et sans 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 de très petite à très grande envergure et elles m'ont bien servi, moi et mes équipes. Postulez dans l'ordre indiqué à mesure que votre projet se développe:
Utilisez 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.
Modularisez votre code (en fonction du langage et de l'environnement de programmation, utilisez des classes, des modules, des packages, des composants).
Documentez votre code. Cela inclut une documentation récapitulative en haut de chaque fichier (qu'est-ce que cela fait? 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?).
Ajoutez TODO
et FIXME
commentaires pendant que vous codez. Cela aide à se rappeler les pourquoi et les bizarreries qui entreront inévitablement dans votre base de code et qui vous demanderont 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
Prenez l'habitude de dessiner des diagrammes pour documenter la structure et les comportements complexes tels que les séquences d'appels entre modules/objets/systèmes, etc. Personnellement, je préfère MLet car il est rapide à utiliser, crée de jolis graphismes et, surtout, ne vous gêne pas. Mais bien sûr, vous devez utiliser n'importe quel outil de dessin qui vous convient. N'oubliez pas que le but de tels dessins est de communiquer succinctement, non de spécifier un système dans les moindres détails (!!).
Ajoutez des tests unitaires dès le début. Les tests unitaires sont non seulement parfaits pour les tests de régression, mais constituent également une forme de documentation d'utilisation pour vos modules.
Ajoutez une documentation externe au code dès le début. Commencez avec un README qui décrit les dépendances requises pour exécuter et développer le projet, comment l'installer, comment l'exécuter.
Prenez l'habitude d'automatiser les tâches répétitives . Par exemple. les cycles de compilation/construction/test doivent être scriptés sous une forme quelconque (par exemple en JavaScript, utiliser grunt
, en Python fabric
, en Java Maven
). Cela vous aidera à vous mettre rapidement au courant lorsque vous reviendrez.
Au fur et à mesure que votre projet se développe, ajoutez plus de documentation en en générant des documents de code source (en utilisant une forme de commentaires de style JavaDoc et un outil approprié pour générer du HTML ou = PDF à partir de celui-ci).
Si votre projet se développe au-delà d'un seul composant et a un déploiement plus complexe, assurez-vous d'ajouter la 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 infimes.
Il y a beaucoup de longues réponses. Voici un petit résumé de ce qui m'aide le plus:
Cependant, les différences, les commentaires de validation, les notes post-it, les listes de tâches ou le tableau Kanban peuvent être mal interprétés au fil du temps en raison du manque de contexte. Voici donc la chose la plus importante:
Je tiens un journal quotidien de mon travail. Qu'est-ce que j'ai fait aujourd'hui, 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.
Quand je reviens à un projet après un certain temps, j'ai lu les dernières entrées du journal pour me mettre au courant du projet. Tous ces petits détails quotidiens sont extrêmement importants pour se souvenir du processus de développement. Ils font vraiment beaucoup de différence par rapport à une liste de tâches ou à la documentation régulière d'un projet, car ils vous rappellent ce que c'était que de travailler sur le projet, et pas seulement comment utiliser le produit.
Pour moi, je trouve que la méthode la plus simple pour reprendre des projets est juste de garder un enregistrement constant des notes sur votre travail. Je trouve que "OneNote" de Microsoft est particulièrement bon pour conserver et regrouper des pages de notes. En particulier, la barre de recherche facilite la recherche rapide de vos notes sur quelque chose.
Voici certaines choses que je fais dans OneNote qui m'aident à reprendre l'avancement des projets:
Journaux quotidiens/hebdomadaires - Gardez 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 garde également une liste de tâches distincte pour les projets sur lesquels je travaille afin de me souvenir de ce que je n'ai pas encore fait. pour un projet. Je laisse parfois aussi // TODO: des éléments dans mon code.
Notes de projet - Les choses 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, courriels pour le projet et liens vers la documentation du projet.
Ainsi, chaque fois que je reviens à un projet, je peux ouvrir mes notes et presque instantanément, je peux voir combien de progrès ont été réalisés sur le projet, combien de travail il reste à faire et même voir mon cheminement de pensée.
En plus des suggestions sur le suivi de projet, les listes de tâches, Trello, etc., quelque chose 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 défaillant à implémenter chaque fois que vous revenez au projet (demain , la semaine prochaine ou le mois prochain)
Asseyez-vous, faites des "tests" et reprenez là où vous vous étiez arrêté.
En plus des commentaires/listes de tâches/commits, il est important d'être réaliste.
Selon la taille, la complexité et l'état dans lequel vous avez quitté votre travail, la reprise d'un projet peut prendre un certain temps. Pour une base de code substantielle de nombreux composants en interaction, il pourrait prendre des jours pour atteindre la vitesse maximale.
Une bonne vieille patience sera utile.
Lorsque submergé après être revenu à un projet après un certain temps, je prends généralement l'unité de tâche la plus simple et la plus petite et je 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. Le plus souvent, je me retrouve à reprendre automatiquement des tâches de plus en plus importantes en quelques heures.