Eu estava trabalhando em um projeto há três meses e, de repente, outro projeto urgente apareceu e me pediram para mudar minha atenção.

A partir de amanhã, voltarei ao projeto antigo. Percebo que não me lembro exatamente do que estava fazendo. Não sei por onde começar.

Como posso documentar um projeto para que, a qualquer momento, não demore mais do que alguns minutos para sair de onde eu saí. Existem práticas recomendadas?

Eu só queria contribuir com alguns conselhos que não serão úteis na sua situação atual, mas você pode começar a implementá-lo agora para ajudar no futuro.

É claro que existem candidatos óbvios, como listas de tarefas e registros de problemas; analisar os problemas adicionados recentemente deve fornecer uma pista sobre o que você estava fazendo quando foi retirado do projeto.

Nos projetos anteriores em que trabalhei, esperava-se que as pessoas mantivessem um registro do projeto como parte do processo de gerenciamento da qualidade. O conteúdo não era muito claramente especificado, mas a idéia era manter um registro diário das coisas relacionadas ao projeto que podem ser úteis para o trabalho contínuo no futuro ou para as atividades de revisão após a conclusão; por exemplo:

• Observações sobre a qualidade do projeto

  esse código pode usar alguma refatoração

  fez uma rápida implementação para que isso funcionasse, mas o ABC seria melhor.

• Itens / problemas de tarefas que você não gostaria de registrar formalmente em um rastreador de problemas

  "deve fazer esse método funcionar, x < 0mas isso está fora do escopo.

• Decisões de design - especialmente as não triviais.

  Nossa função de classificação padrão executa uma classificação rápida, mas isso não preserva a ordem dos itens iguais nas condições de classificação necessárias aqui.

  O algoritmo óbvio seria ABC, mas isso falha aqui porque xpode ser negativo, por isso precisamos da forma generalizada ( link da Wikipedia ).

• Problemas encontrados e como você os solucionou. Muito importante, na minha opinião pessoal: sempre que encontrar um problema, observe-o no log.

  Verifiquei o código, mas deu o erro XYZ0123. Acontece que primeiro tive que atualizar o componente C para a versão 1.2 ou superior.

Os dois últimos pontos são muito importantes. Muitas vezes encontrei uma situação ou problema semelhante - às vezes em um projeto completamente diferente - e pensei "hmm, lembro-me de passar um dia nisso, mas qual era a solução novamente?"

Quando você voltar a um projeto depois de um tempo, a leitura do log do projeto (seja seu ou do desenvolvedor mais recente) deve colocá-lo de volta ao fluxo que você tinha quando saiu e avisá-lo sobre algumas das armadilhas que você caso contrário, poderá cair novamente.

As listas de tarefas são mágicas. Geralmente, você precisa manter uma lista de tarefas ativas para cada projeto e, mesmo que esteja ocupado com a programação, se você pensa em algo que precisa ser feito e não pode fazê-lo imediatamente, ele entra na lista. Mantenha essa lista em um local conhecido, em uma planilha ou arquivo de texto na pasta do projeto eletronicamente ou no seu diário de papel.

Além disso, sempre que você deixar o projeto durante a noite (ou no final de semana), faça um post-it e escreva a próxima coisa que você faria na nota e cole-a no monitor. Isso aumenta a probabilidade de você voltar rapidamente na manhã seguinte.

Editar :

Devo mencionar que as listas de afazeres (listas de afazeres priorizadas especificamente segregadas por local e projeto) são uma parte essencial do livro Getting Things Done , que eu achei altamente influente.

O que fazer agora?

Agora, a partir de amanhã, voltarei ao meu projeto antigo e percebo que não me lembro exatamente do que estava fazendo e por onde começar!

Meu palpite é que você não fez nada na próxima seção. Portanto, procurar uma lista de tarefas não funcionará.

1. Bloqueie um período de tempo. Coloque isso no seu calendário e passe um tempo revisando o projeto. Isso pode estar revisando a documentação, o código, os requisitos etc.
2. Aceite que levará um tempo para voltar à velocidade. Certifique-se de que todos os envolvidos percebam isso. Certifique-se de que você perceber isso.
3. Comece com uma pequena tarefa. Reconstrua a sua confiança, fazendo algo pequeno. Se você tiver uma lista de novos itens, trabalhe primeiro com os menores. Isso não apenas recupera sua confiança, mas também ajuda a se familiarizar com o projeto.

Como tornar isso melhor para si mesmo no futuro?

Desejo saber como documentar o projeto de forma que, sempre que olho para trás, não demore mais do que alguns minutos para sair de onde eu parti!

Primeiro, você precisa ter um sistema para acompanhar seus todos. Você tem esse sistema agora? Como você gerencia seu projeto atual?

Eu poderia ser atropelado por um ônibus amanhã e minha equipe teria uma boa idéia de mais de 90% dos meus itens de ação. Isso ocorre porque eu tenho um sistema coeso para documentar meus:

• Todos imediatos (<itens de 1 semana)
• "É bom ter" todos
• Marcos e macro todos (onde os detalhes não são significativos)
• Requisitos / notas de reunião

Além disso, eu uso um VCS e comento meu código, quando apropriado.

Isso funciona para mim e minha equipe desde que eu sou o desenvolvedor principal. Você pode usar algum tipo de sistema de rastreamento de problemas para uma equipe. Ou um backlog ao trabalhar com o Agile. Há uma tonelada de opções. Se você está realmente interessado nisso, leia Getting Getting Done ou outras metodologias relevantes de gerenciamento de tarefas, que existem quase exatamente por causa do que você descreve.

Qual é o objetivo?

As especificidades do sistema são menos relevantes do que o sistema coeso e você o utiliza . E que você use. E use-o. Isso é importante. Mais importante do que um bom sistema perfeito que você não usa. Não faça "bem, a maior parte do meu trabalho está aqui, mas alguns estão na minha cabeça" ou você vai se odiar voltando a um projeto.

Além disso, verifique se seus comentários explicam "por que" em vez de apenas o "quê" para o código. É muito mais fácil ler "isto é para corrigir um bug no IE8" e lembrar o que o código faz do que um comentário simplesmente explicando os detalhes técnicos.

Na minha opinião, existem duas partes para "retomar" um projeto de código:

1. Determinando de onde você parou
2. Lembrando o que resta você tem que fazer

Essa é uma daquelas coisas que, se você estiver controlando a versão da maneira certa, será o seu "outro cérebro".

De onde você parou ? Contanto que você esteja enviando código com freqüência, observe seu último conjunto de alterações. Provavelmente, você jogará algo em sua mente. Caso contrário, observe os poucos anteriores, começando pelos commits mais antigos e repetidos.

Quanto ao que resta a fazer , um backlog deve servir a esse propósito (ou uma lista de tarefas ou o que você quiser nomear. Basicamente, itens para o futuro).

Não sou desenvolvedor de software em período integral. Sou um programador que corta as noites e fins de semana. Por esse motivo, quando o trabalho ou outras coisas que não são de programação têm prioridade mais alta, às vezes eu posso passar dias e semanas sem sequer exibir meu código com um olhar. O acima exposto provou ser bastante eficaz.

Esta não é uma resposta completa - já existem várias muito boas mencionando coisas importantes, como usar o VCS e o software de gerenciamento de projetos -, mas um adendo que acrescenta alguns pontos que eu não vi em nenhum outro, que eu acho que é muito útil, e espero que outras pessoas também achem útil.

1. Nenhuma tarefa é muito cedo ou muito pequena para ser anotada

As pessoas costumam fazer listas de tarefas para as coisas que planejam fazer no futuro , mas como a programação exige concentração e como podemos ser interrompidos a qualquer momento , achei útil anotar até o que estou fazendo agora, ou o que estou prestes a começar em questão de segundos . Você pode sentir que está na zona e não pode esquecer a solução que acabou de acertar naquele momento aha , mas quando seu colega de trabalho cai no seu cubo para mostrar uma foto do dedo infectado dele , e você está capaz de finalmente se livrar dele, começando a roer seu próprio braço , você pode desejar ter anotado uma nota rápida, mesmo que apenas em uma nota Post-It ™.

É claro que algum outro meio mais persistente pode ser melhor (gosto particularmente do OmniFocus ), mas a questão é pelo menos tê-lo em algum lugar , mesmo que você termine em 20 minutos e jogue o Post-It ™ fora. Embora você possa descobrir que essas informações se tornam úteis, colocar folhas de ponto ou faturas para o cliente ou quando seu chefe / cliente perguntar o que você está trabalhando e não se lembra. Se você soltar todas essas anotações em uma caixa, gaveta ou pasta, quando ocorrer uma grande interrupção - um projeto de interrupção -, será possível examiná-las e lembrar-se de muitas coisas que você fez para levar seu código ao ponto em que você encontre-o quando retornar ao projeto.

2. Use um quadro branco em sua mesa para capturar idéias gerais

Eu tenho um quadro branco de 3 "x 4" ao lado da minha mesa; portanto, quando inicio um projeto, posso pensar em soluções para todos os problemas que percebo em um projeto. Pode ser diagramas arquitetônicos, casos de uso, listas de riscos e obstáculos ou qualquer coisa que lhe pareça relevante.

Algumas abordagens mais formalizadas exigem que você gere diagramas e casos de uso e assim por diante como "entregáveis" em algum formato eletrônico ou em papel, mas acho que isso pode criar muito trabalho extra e se tornar uma série de subprojetos que terminam se divorciar do objetivo real do projeto principal e apenas parte de um processo formalizado que você precisa fazer, mas que ninguém presta muita atenção. Um quadro branco é a coisa mais simples que realmente funciona, pelo menos na minha experiência. É tão persistente quanto você deseja (com uma câmera) e, o mais importante, permite que você descubra suas idéias imediatamente.

Eu acho melhor com uma caneta na mão, então jogar meus pensamentos em uma superfície branca vem naturalmente para mim, mas se você não acha que esse é o seu caso, aqui estão algumas perguntas que podem ajudá-lo a decidir o que é relevante :

• Se eu fosse o desenvolvedor líder, prestes a ficar em lua de mel por 3 meses enquanto outros desenvolvedores concluíram o projeto, que direção geral eu gostaria de dar a eles? Que ideias eu gostaria de ter para garantir que eles soubessem ou quais abordagens eu gostaria de garantir que elas tivessem? De quais bibliotecas ou outras soluções úteis eu gostaria de ter certeza de que elas estavam cientes?
• Se esse projeto fosse minha ideia de um milhão de dólares, eu sabia que garantiria minha futura independência financeira, mas estava programado para uma cirurgia crítica que me incapacitaria por 3 meses, o que eu gostaria que meu futuro tivesse para garantir a conclusão bem-sucedida de o projeto?

(Quando escrevo as idéias pela primeira vez, só me preocupo com elas fazendo sentido para o meu eu atual. Depois que elas caem, posso olhar mais criticamente para elas e fazer alterações para garantir que elas façam sentido para o meu eu futuro ou para os outros. Preocupar-se demais sobre a comunicação com os outros à medida que você os escreve inicialmente pode levar ao bloqueio dos escritores - uma mente entupida por objetivos concorrentes.

Eu recomendo que você gaste o dinheiro para comprar um quadro branco decente, pelo menos 3 "x 4", e pendure-o no espaço em que você normalmente trabalha. Há muitas vantagens de um quadro branco físico sobre qualquer sistema virtual.

• E grande. Ao ocupar muito espaço, sua presença é sentida, e os planos nele parecem fazer parte do seu espaço de trabalho, ajudando a direcioná-lo na direção certa o tempo todo.
• Ele existe persistentemente: você não precisa iniciar um determinado aplicativo ou site para acessá-lo e não corre o risco de esquecer como chegar a ele ou esquecer que ele está lá.
• É imediatamente acessível quando você tem uma ideia que deseja pensar.

Você perde muitos dos benefícios se usar um quadro branco em uma sala de reunião e tirar uma foto com seu telefone. Se você ganha dinheiro com a programação, vale a pena o custo de um quadro branco decente.

Se um outro projeto interromper o que encheu o quadro branco, talvez seja necessário recorrer ao instantâneo do telefone, mas pelo menos você terá isso em três meses quando o projeto "urgente" for concluído e você precisará volte para o outro. Se você quiser recriá-lo em seu quadro branco, provavelmente levará apenas 15 minutos e poderá descobrir que pode melhorar bastante no processo, o que faz com que esse pequeno investimento de tempo valha a pena.

3. Informar as partes interessadas sobre o custo de interromper um projeto

Acho útil a metáfora de um avião: iniciar e concluir um projeto é como pilotar um avião. Se você sair no meio do voo, o avião não ficará parado no ar, esperando que você volte a ele, e você precisará de alguma maneira de viajar do projeto / vôo atual para o próximo. De fato, se você estiver no meio de um voo de Phoenix para Fargo e lhe disseram que precisa interromper o voo para pegar outro avião de Denver para Detroit, precisará pousar o primeiro avião em Denver (que felizmente, não está longe da sua trajetória de voo - nem sempre é o caso de interrupções reais) e alguém precisa descobrir o que fazer com a carga e os passageiros. Eles não vão apenas sentar e esperar para sempre.

O ponto disso para os projetos é que a transição de um projeto para outro implica uma grande despesa de tempo e deixa muitas perdas a serem resolvidas.

Em um projeto, há obviamente e inevitavelmente muita coisa em sua cabeça enquanto você trabalha, e nem todo pensamento pode ser serializado em um meio escrito, e nem todo tipo de pensamento que é serializado permanecerá quando desserializado. Embora possamos capturar parcialmente nossos pensamentos por escrito, é um formato com perdas.

O problema (a meu ver) é que os gerentes de projetos e outras pessoas de negócios pensam nos projetos como uma série de etapas que podem ser reordenadas com freqüência (a menos que exista uma dependência explícita no gráfico de Gantt) e podem ser facilmente distribuídas entre as pessoas ou atrasado até que seja mais conveniente para os negócios.

Qualquer pessoa que tenha feito alguma programação sabe que os projetos de software não podem ser tratados como blocos de Lego para serem movidos da maneira que você quiser. Acho que a metáfora das viagens aéreas, pelo menos, dá às partes interessadas algo concreto que elas podem pensar que claramente não pode ser tratado como uma série de etapas díspares a serem reordenadas por um capricho. Pelo menos, é fácil entender o seu argumento de que há um custo para essas interrupções. É claro que ainda é uma decisão deles, mas você deseja conscientizá-los antes que eles interrompam um projeto para dar outro. Não seja combativo, mas ofereça informações úteis e a perspectiva útil do desenvolvedor, pronto para fazer o que for necessário, mas apenas ofereça informações das quais eles talvez não saibam se você não lhes contar.

Em resumo:

1. Anote tudo o que você está prestes a fazer, mesmo que não pense que possa precisar. Até um lápis curto bate uma longa memória.
2. Faça um brainstorm do quadro geral em um quadro branco físico ao qual você tenha acesso persistente.
3. Você pode evitar interrupções no projeto se conscientizar os tomadores de decisão de que há um custo para essas interrupções e, pelo menos, você definirá expectativas para que eles saibam que o projeto levará um pouco mais de tempo quando você o reiniciar.

Você pode consultar o histórico do projeto em seu software de controle de versão de três meses atrás. Leia suas mensagens de confirmação e as diferenças mais recentes para ter uma idéia do que estava trabalhando.

O uso de um sistema de controle de origem com estratégias apropriadas de ramificação e fusão, em conjunto com sistemas de rastreamento de problemas (como Redmine ou GitHub ), ajuda a compartimentar as alterações que você fez, orientar e documentar seu 'contexto' ausente como uma parte natural do fluxo de trabalho.

1. Antes de iniciar uma alteração de código, verifique se há um 'problema' registrado no seu sistema de rastreamento de problemas. Isso cobre a peça que faltava "o que eu estava fazendo" do seu trabalho.
2. Crie uma ramificação no seu sistema de controle de origem e verifique se as alterações nessa ramificação estão relacionadas SOMENTE ao problema mencionado acima. Isso o ajudará a isolar as alterações e fornecerá um histórico da mudança, respondendo à pergunta "de onde eu parei?" depois que você voltar a trabalhar nele mais tarde.
3. Quando terminar a alteração, junte-a novamente ao seu tronco e feche o problema.

Há muitas respostas longas. Este é breve sobre o que mais me ajuda:

• Código limpo.
• Código limpo.
• Código limpo.
• Controle de versão (diffs e confirmar comentários).
• Uma nota de Post-It ou uma lista de tarefas ou um Kanban-Board (consulte, por exemplo, Trello e Evernote)

No entanto, Diffs, Commit comments, Post-It notes, Todo-Lists ou Kanban-Board podem ser mal interpretados ao longo do tempo por falta de contexto. Então, aqui está a coisa mais importante:

CÓDIGO LIMPO.

Como posso documentar um projeto para que, a qualquer momento, não demore mais do que alguns minutos para sair de onde eu saí.

Primeiro, isso implica que há alguma descrição de alto nível e estrutura de código no projeto que você pode entender facilmente em alguns minutos - em oposição a um zilhão de linhas de código sem estrutura aparente e sem comentários.

Existem práticas recomendadas?

A seguir, são apresentadas as melhores práticas que adotei ao longo de uma carreira de mais de 20 anos em projetos muito pequenos a muito grandes e elas serviram a mim e a minha equipe. Aplique na ordem listada à medida que seu projeto cresce:

1. Use o controle de versão para obter um histórico gratuito do que aconteceu, quando e quem aplicou as alterações. Também oferece fácil retorno a uma versão anterior a qualquer momento.

2. Modularize seu código (dependendo da linguagem e do ambiente de programação, use classes, módulos, pacotes, componentes).

3. Documente seu código. Isso inclui a documentação resumida na parte superior de cada arquivo (o que isso faz? Por que? Como usá-lo?) E comentários específicos no nível de funções, procedimentos, classes e métodos (o que isso faz? Argumentos e valores de retorno / tipos? efeitos colaterais?).

4. Adicione TODOe FIXMEcomente enquanto estiver codificando. Isso ajuda a lembrar os porquês e as peculiaridades que inevitavelmente entrarão em sua base de código e que mais tarde você terá que perguntar ao WTF ?! . Por exemplo:

   //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. Crie o hábito de desenhar diagramas para documentar a estrutura e o comportamento complexo, como sequências de chamadas entre módulos / objetos / sistemas, etc. Pessoalmente, prefiro o UMLet , pois é rápido de usar, cria bons gráficos e, o mais importante, não interfere no seu caminho. . Mas é claro que você deve usar qualquer ferramenta de desenho que considere adequada. Lembre-se de que o objetivo de tais desenhos é se comunicar de forma sucinta, não especificar um sistema em detalhes minuciosos (!!).

6. Adicione testes de unidade logo no início. Os testes de unidade não são ótimos apenas para testes de regressão, mas também são uma forma de documentação de uso para seus módulos.

7. Adicione documentação externa ao código logo no início. Comece com um README que descreva as dependências necessárias para executar e desenvolver o projeto, como instalá-lo, como executá-lo.

8. Crie o hábito de automatizar tarefas repetitivas . Por exemplo, os ciclos de compilação / compilação / teste devem ter scripts de alguma forma (por exemplo, no uso de JavaScript grunt, em Python fabric, em Java Maven). Isso ajudará você a acelerar rapidamente quando voltar.

9. À medida que seu projeto cresce, inclua mais documentação gerando documentos de código-fonte (usando alguma forma de comentários no estilo JavaDoc e uma ferramenta apropriada para gerar HTML ou PDF a partir dele).

10. Se o seu projeto crescer além de um único componente e tiver uma implantação mais complexa, adicione documentação de design e arquitetura . Observe novamente que o objetivo disso é comunicar estrutura e dependências, em vez de detalhes minuciosos.

Além das sugestões sobre o rastreamento do projeto, as listas de tarefas, o Trello, etc., algo que li uma vez que ajuda se você pratica o TDD é sempre se afastar do projeto com um novo teste de falha a ser implementado sempre que você voltar ao projeto (amanhã , na próxima semana ou no próximo mês)

Sente-se, faça 'Executar testes' e continue de onde parou.

Além dos comentários / listas de tarefas / confirmações, é importante ser realista.

Dependendo do tamanho, da complexidade e do estado em que você deixou o seu trabalho, o início de um projeto pode demorar um pouco. Para uma base de código substancial de muitos componentes em interação, pode levar dias para atingir a velocidade máxima.

Boa e velha paciência será útil.

Quando sobrecarregado depois de voltar a um projeto depois de um tempo, geralmente pego a unidade de tarefa mais simples e menor e a implemento. Isso me impede de me perder tentando lembrar de muitas coisas ao mesmo tempo e aumenta a confiança um pouco. Na maioria das vezes, eu me pego automaticamente pegando tarefas cada vez maiores em poucas horas.

Eu mantenho um diário diário do trabalho que faço. O que eu fiz hoje, o que foi difícil hoje, qual é o próximo passo, que idéias eu tive hoje para o futuro. Também adiciono um pouco de narrativa sobre como foi o dia: houve uma conversa ou reunião interessante? Algo ficou com raiva ou deleite? Isso ajuda a colocar as coisas em perspectiva quando mais tarde leio meu diário.

Quando volto a um projeto depois de um tempo, li as últimas entradas do diário para me familiarizar com o projeto. Todos esses pequenos detalhes do dia a dia são incrivelmente importantes para lembrar o processo de desenvolvimento. Eles realmente fazem muita diferença em comparação com uma lista de tarefas ou documentação regular do projeto, pois lembram como foi trabalhar no projeto e não apenas como usar o produto.

Para mim, acho que o método mais simples de retomar projetos é apenas manter um registro constante de anotações em seu trabalho. Acho que o 'OneNote' da Microsoft é particularmente bom para manter e agrupar páginas de anotações. Em particular, a barra de pesquisa torna extremamente fácil encontrar rapidamente suas anotações sobre algo.

Aqui estão algumas coisas que faço no OneNote que me ajudam a retomar o progresso nos projetos:

• Registros diários / semanais - Mantenha um registro diário ou semanal do progresso para ajudá-lo a descobrir o progresso que você já fez em um projeto.

• Lista de tarefas - eu tenho uma lista geral de tarefas, mas também mantenho uma lista de tarefas separada para os projetos nos quais estou trabalhando, para lembrar as coisas que ainda tenho que fazer por um projeto. Às vezes, também deixo // TODO: itens no meu código.

• Notas do projeto - As coisas que observo incluem links para itens de rastreamento de problema / projeto, trechos de código, problemas encontrados, decisões tomadas, planos e descrições de possíveis soluções, lista de alterações de código, links para o diretório do repositório de códigos, e-mails para o projeto e links para Documentação do projeto.

Assim, sempre que volto a um projeto, posso abrir minhas anotações e quase instantaneamente posso ver quanto progresso foi feito no projeto, quanto trabalho resta para fazer e até ver minha linha de pensamento.

Para projetos simples, faço o seguinte:

1. Um arquivo README simples no diretório raiz (que, portanto, também acabará no controle de versão), onde observo o que aparecer durante o desenvolvimento: coisas para fazer, bugs, melhorias / idéias. Esse é o primeiro arquivo que lerei se tiver que colocar o projeto em segundo plano.
2. Comentários TODO / FIXME / XXX
3. Eu também costumo usar ToDoList