Como introduzir código para um colega

Como você introduz a base de código, que pode ser bastante complexa e confusa com muitas "dicas" para um novo membro da sua equipe?

Eu acho que a maneira mais fácil seria ter a arquitetura geral definida com diagramas e levar algumas semanas (ou meses) dando à nova pessoa tarefas bem definidas (e com escopo bem definido) à medida que ela se acostumar com o código.

No entanto, como consultor (e funcionário júnior), nem sempre posso ter isso devido a restrições de tempo ou a designações de funções de equipe. (Eu estive nesse projeto em particular duas vezes mais do que qualquer outra pessoa, de modo que "junior" não é de forma alguma "sabe menos sobre o código / projeto".)

Fui encarregado algumas vezes agora de apresentar um novo membro ao projeto e ao código e, infelizmente, toda vez que percebo que não sou muito melhor nisso do que o anterior. Adoro diagramas e imagens, mas muitas vezes sinto que eles não respondem adequadamente à complexidade de um sistema. (E todas as "pegadinhas" dos pequenos?)

O projeto está chegando a um ponto em que vamos entregá-lo ao cliente e, para tornar as coisas mais desafiadoras, a pessoa com quem vou fazer uma transferência de conhecimento está praticamente fora da faculdade. (Não que eu seja muito melhor ao fazer transferências de conhecimento com desenvolvedores seniores.)

Eu participo de um grupo de usuários uma vez por mês e de outras oportunidades à medida que surgem, por isso não estou acostumado a ser apresentado a novos tópicos, mas sinto minha capacidade de replicar um compartilhamento de conhecimento eficaz lamentavelmente inadequado.

Qualquer conselho seria muito apreciado. Estou procurando principalmente uma orientação que possa seguir. Por exemplo: por onde você começa? Como você prossegue? Como você cobre tecnologias ou padrões desconhecidos da parte do ouvinte sem precisar tirar o dia todo? Onde você vincula a lógica de negócios à estrutura de código?

Obrigado!

(Como sempre, fique à vontade para editar a pergunta como achar melhor.)

O primeiro passo é remover as "dicas" do código. Código claro, conciso e consistente é mais fácil de entrar, trabalhar e depurar.

Por onde você começa?

Pergunto aos recém-chegados como eles querem entrar na base de código. Todo mundo aprende de maneira diferente. Algumas pessoas gostam de ter pequenas tarefas para trabalhar. Alguns gostam de depurar código existente. Alguns querem ver o código em execução para entender o que ele faz. Alguns querem começar no ponto de entrada e apenas navegar. Alguns querem diagramas visio ... Nenhum padrão definido funcionará melhor para todos.

Como você cobre tecnologias ou padrões desconhecidos da parte do ouvinte sem precisar tirar o dia todo?

Eu os evito. Que sejam caixas pretas até que o recém-chegado pergunte sobre elas. Em seguida, forneça informações suficientes para entender o que está acontecendo, com a dica de que eles podem aprender mais em seu próprio tempo ou perguntar mais tarde quando as coisas em geral são mais conhecidas.

Onde você vincula a lógica de negócios à estrutura de código?

Eu tento não. É quase sempre melhor para o recém-chegado aprender por conta própria, para que fique na mente deles numa estrutura mais natural para o seu modo de pensar.

Uma coisa a lembrar é manter as instruções curtas. As pessoas tendem a verificar rapidamente, portanto, mais instruções nesse momento simplesmente não 'grudam'. Mostre-lhes coisas por 15 a 60 minutos (pessoas diferentes têm diferentes períodos de atenção) e depois faça uma pausa de 5 a 30 minutos para processá-las.

Na minha experiência, uma boa maneira de preencher a lacuna entre a ampla visão geral que um diagrama de arquitetura fornece e os detalhes de realmente trabalhar com o código é fazer uma pesquisa detalhada do sistema, ou seja, o que acontece quando chega uma solicitação (para código do servidor ) ou um usuário faz uma entrada (para o código do cliente) e explica passo a passo todas as camadas de código envolvidas.

Outra maneira é um "tour guiado" do código-fonte, ou seja, percorra os pacotes / namespaces / modules / diretórios e explique o que o código de cada um deles faz em geral. Obviamente, isso exige que o código seja apresentado de maneira um tanto lógica.

Você não está ensinando a eles a base de código, mas sim o seu trabalho. Não tente pensar no que eles podem precisar, veja o que você realmente precisa saber ao fazer seu trabalho.

Puxar para cima os últimos meses da história bug tracker, histórias de usuários scrum, relatórios de status, e commits de controle de origem. Quais arquivos você tocou mais? O código é mais problemática? Quais tarefas demoraram mais? As chances são de que, se você não tocou nos últimos meses, não é tão importante quanto você imagina.

Veja a pilha de impressões em sua mesa. Verifique se o seu navegador história recente. Procure e-mails salvos aos quais você se refere com frequência, contatos que você usa, documentos que você baixou. Algumas das referências mais úteis que passei para outras pessoas são as anotações que guardei para mim quando aprendi ou desenvolvi o sistema pela primeira vez. O material de referência é mais útil para você ?

Em seguida, abra seu backlog conhecido. Que coisas você precisaria pesquisar para concluir essas tarefas? Que áreas de código mais provável conter o problema? Transmitir essas informações como se estivesse fazendo anotações para si mesmo.

Se você se referir a gráficos ou diagramas em seu trabalho diário, inclua-os. Se você nunca se incomodou em fazer um, provavelmente também não será útil para o seu sucessor / colega.

Uma das tarefas mais difíceis ao ensinar é tentar se colocar no lugar delas. Neste caso, você está em seus sapatos. Aproveite ao máximo.

O trabalho de suporte é o melhor, pegue um bug fácil e conduza-o pelas áreas onde será encontrado. eles aprenderão rapidamente como o código se encaixa. Naturalmente, eles estarão vindo para fazer perguntas sobre este erro e a base de código, mas eles vão chegar lá (e você vai ter um bug corrigido). Muitas vezes é muito mais fácil de descobrir as coisas com exemplos, da mesma forma, é mais fácil de trabalhar para fora uma base de código, executando através dele em um depurador.

Se você não tiver certeza das alterações no código (ou elas são, normalmente eu não tenho certeza das minhas correções de código até que eu esteja familiarizado com a base de código), você pode revisá-lo antes de fazer o check-in.

Obviamente, suas idéias existentes de visões gerais abrangentes e diagramas de blocos são os primeiros passos essenciais.