O que você deve deixar para seus sucessores?

Suponha que você seja o único desenvolvedor a deixar um emprego. Que tipo de informação / material, fora do próprio código, você deve criar e deixar para sua substituição?

Uma resposta óbvia é "o que você deseja em um novo emprego", com certeza, mas já faz um tempo desde que eu comecei um novo trabalho e esqueço as coisas mais importantes que eu precisava naquela época.

Estou pensando:

• contas / senhas
• localização de equipamentos, backups, CDs de software

O quê mais?

• Contas e Senhas
• Informação do servidor
• Good code
• Documentação
  • Os diagramas e explicações do banco de dados são incríveis
  • Lista de esquisitices no código
• Procedimentos
• Explicação de processos manuais ou trabalho ocasional, não óbvio,
• Lista de programas que eles usaram ou acharam úteis
• Informações de Contato ;)

Uma forte xícara de café e uma nota de desculpas.

É o que eu desejo que eu estava à esquerda.

• Documentação. Quão difícil é escrever alguns comentários? Crie notas, notas de implantação, movendo as notas do sistema. O que fazer quando você reiniciar e tudo acabar.
• Papéis. Escreva por que isso está sendo feito dessa maneira, para que eu não precise me perguntar por que você não está fazendo de outra maneira. Como o sistema de backup funciona, como o servidor responde a cargas, testes, casos de teste, casos de uso.
• Notas. "Ao usar o banco de dados, nunca diga SELECT * FROM clients. Não sabemos por que, mas ele despeja o banco de dados" .

Meu endereço de e-mail ou talvez até o número de telefone.

Na minha experiência, é difícil escrever todos os detalhes, portanto, o melhor é estar disponível (até certo ponto) se seus sucessores precisarem de mais informações.

Documentação dos programas que você escreveu, por exemplo, sua finalidade, localização dos arquivos de origem para desenvolvimento futuro, senhas, etc.

Isso pode estar dentro do código como um comentário ou fora de vista.

Mais do que apenas documentação, eu gostaria de saber por que certas decisões foram tomadas quando foram tomadas. Atualmente, estamos usando o SWIG em um projeto e um dos outros desenvolvedores queria saber por que simplesmente não usamos o Boost :: Python. A resposta simples foi que o cliente não permitiu o uso do Boost na época. Agora é uma história diferente.

Essas coisas os ajudarão não apenas a entender o projeto, mas também a quais limitações / restrições / desafios sua implementação superou. Isso lhes dará um ponto de partida para manutenção futura e aumento de recursos.

Uma coisa que eu não vi mais ninguém mencionar (embora eu possa ter esquecido) é documentar como configurar um ambiente de desenvolvimento. Percebo que, na maioria das vezes, é só instalar algumas coisas, atualizar, compilar e pronto. Entretanto, às vezes, há mais do que isso (o SharePoint é uma situação que vem à mente) e documentar qual capacitador de fluxo deve ser configurado de que maneira será muito útil para a pobre alma que está seguindo você.

Se for um programa de desktop, como criar todo o sistema a partir do zero (pode haver vários programas separados), como criar um pacote para distribuição (quais dependências ele possui, por exemplo, versões do .NET) e como implantá-lo nos servidores para download, se aplicável, ou grave-o em um CD ou DVD.

Se for um programa baseado na Web, o FTP e (se aplicável) o acesso SSH ao servidor e quais ferramentas são usadas para criar e testar localmente o código.

Se for um sistema incorporado, siga as instruções completas sobre a construção da imagem binária, quais ferramentas são usadas, como baixar e atualizar o código no produto, como configurar o sistema de arquivos no dispositivo, se houver.

Recentemente, deixei um emprego em circunstâncias semelhantes a você (eu não era o único desenvolvedor, mas realmente éramos apenas dois de nós, então eu tinha bastante conhecimento que o outro cara não tinha (e vice-versa, claro)).

Em termos de documentação normal, é importante documentar uma visão geral de todo o sistema. Os componentes individuais já estão documentados no código, mas a interação entre os componentes e por que isso faz isso ou por que isso precisa falar com esse componente é importante e nem sempre é fácil de descobrir apenas depurando / observando o código.

Então, cerca de um mês antes de eu sair, toda vez que fazia algo que só eu podia fazer, escrevia exatamente o que havia acontecido, o que tinha que fazer e por quê. Este era geralmente um caso de "havia um bug no componente xyz; para corrigi-lo, eu sabia procurar no arquivo abc por causa do X, então eu tinha que fazer isso, isso e aquilo".

Claro, deixei meu endereço de e-mail e número de telefone para o caso de surgir algo que eles não conseguissem descobrir por conta própria. Recebi algumas ligações nas primeiras semanas, mas elas foram interrompidas lentamente.

Todos gostaríamos de um diagrama de fluxo de dados completo do sistema com uma lista de requisitos funcionais. Mais do que provavelmente você nunca conseguiu isso quando escreveu o sistema em primeiro lugar! Como na maioria dos lugares, a melhor documentação é provavelmente o código em si; portanto, o que eu mais adoraria é um código bem documentado. Linhas e linhas de comentários no código explicando o que você está tentando fazer técnica e funcionalmente.

A regra nº 1 para documentação não é o que faz, mas por quê . Qual é a história de fundo dos programas executados e o que eles fazem?

Eu acho que o que eu adoraria ver nas documentações além do habitual seria quais recursos foram deixados de fora. Por exemplo, por que certas idéias NÃO foram implementadas ou uma certa plataforma ou método NÃO foi usado (que de outra forma era uma escolha óbvia).

Isso garante que o sucessor sempre saiba o que não deve fazer ou se ele é mais capaz, então talvez ele possa criar uma solução alternativa e fazer com que certos recursos funcionem.

Isso é especialmente aplicável a projetos de código aberto. Pode economizar muito tempo e poder do cérebro!