Como promover a reutilização e documentação de código? [fechadas]

Como líder de equipe de mais de 10 desenvolvedores, eu gostaria de promover a reutilização de código. Escrevemos muito código - muitos deles são repetitivos nos últimos anos. O problema agora é que muitos desses códigos são apenas duplicados de algum outro código ou uma pequena variação deles.

Eu iniciei o movimento (discussão) sobre como transformar código em componentes para que possam ser reutilizados para projetos futuros, mas o problema é que receio que os novos desenvolvedores ou outros desenvolvedores que ignoram os componentes avancem e escreva suas próprias coisas.

Existe alguma maneira de lembrar aos desenvolvedores a reutilização dos componentes / melhorar a documentação / contribuir com o componente subjacente, em vez de duplicar o código existente e aprimorá-lo ou apenas escrever o seu?

Como tornar os componentes facilmente detectáveis ​​e facilmente utilizáveis ​​para que todos os usem?

Acho que todo desenvolvedor conhece os benefícios dos componentes reutilizáveis ​​e deseja usá-los, mas não sabemos como torná-los detectáveis. Além disso, quando os desenvolvedores estão escrevendo código, eles sabem que devem escrever código reutilizável, mas falta de motivação para fazê-lo.

Você precisa de documentação adequada. Deve ser fácil encontrar e navegar. Você também precisa de disciplina. Se já houver uma solução fornecida em suas bibliotecas de códigos reutilizáveis, mas o desenvolvedor optar por usar sua própria solução (sem qualquer motivo adequado), você deve reverter a solução e pedir para ele usar a solução existente.

Também concordo com o comentário de Euphoric à pergunta. Geralmente, é impossível reutilizar qualquer coisa entre projetos diferentes (geralmente todas as operações CRUD parecem iguais, mas geralmente você não pode reutilizá-las).

Ao lado dos fatores já mencionados "documentação", "fácil de encontrar e navegar", "disciplina" e "visualização de código"

código reutilizável deve ser

• fácil de usar (= precisa de exemplos, por exemplo, unittests)
• sem muitas dependências para outros módulos e
• ele deve ter uma API estável, portanto, não preciso atualizar meu aplicativo para usar a biblioteca.

sem os dois últimos itens, é muito mais fácil usar "cópia e herança passada" que não queremos.

Eu acho que a melhor maneira de fazê-los reutilizar o código é motivação. Se você colocar os componentes reutilizáveis ​​em projetos extras, como eufórico sugeriu, faça muito esforço. Onde trabalho, criamos um projeto que executa um conjunto de interfaces predefinidas em planos de execução configuráveis ​​e fornece alguns serviços (por exemplo, classes diferentes para DB_interaction, um serviço FTP, ...). O projeto é um grande sucesso, porque nossos desenvolvedores realmente querem usar a micro-estrutura, pois economiza muito tempo para escrever código-padrão para projetos semelhantes. O mesmo se aplica às bibliotecas de utilitários para listas, cadeias de caracteres, etc., mas nesse caso você deseja usar as existentes uma vez. (por que reinventar o weel?)

Conclusão: permita que seus desenvolvedores experimentem os benefícios de componentes reutilizáveis ​​bem testados. Mas também concordo com a resposta de Andrzej Bobak: muitas coisas não são reutilizáveis, porque são semelhantes, mas não são as mesmas.

Isso vai ser difícil, porque as pessoas gostam de escrever um novo código para componentes simples e gostam de fazer do seu jeito. É muito mais difícil aproveitar e estender uma solução existente do que escrever uma implementação completamente nova com os novos requisitos. O que você precisa fazer, como foi afirmado, é iniciar um processo de revisão de código entre a equipe para ajudar a identificar situações em que um componente existente deveria ter sido usado / estendido em vez de um novo.

Você também precisa manter uma documentação muito boa e completa para que as pessoas possam consultá-la e encontrar facilmente o que precisam. Se a documentação estiver incompleta ou fora de sincronia com a coisa real, as pessoas não serão motivadas a pesquisá-la ou aprimorá-la.

Como líder da equipe, você também deve incentivar as pessoas a se perguntarem se existe um componente semelhante antes de criar o seu próprio e encaminhá-las para a documentação para que possam procurar. Certifique-se de que o processo de revisão de código será detectado se alguém perder um componente existente, mas e se ele já colocar 10 horas de desenvolvimento em sua própria implementação? Você precisa evitar essas situações, aplicando um bom comportamento de pesquisa na equipe.

Enfrentamos esse problema em um grande projeto no qual estou trabalhando atualmente. Tivemos uma rotação de desenvolvedores nos últimos meses, também é uma base de código bastante grande e mesmo os que estão no projeto desde o início não conhecem cada centímetro dele.

Embora o código geralmente seja bem escrito e dividido em pequenas partes com responsabilidades únicas e a documentação esteja lá, é muito fácil perder algo que foi feito. Convenções de nomenclatura consistentes ajudam muito porque é fácil procurar algo em qualquer IDE. A documentação pode ser abrangente, mas, à medida que cresce, é um pouco difícil de ler.

Uma coisa que fizemos que, na minha opinião, melhorou bastante a situação foi a introdução de algo que chamamos de conversas sobre relâmpagos . Sempre que alguém escreve um código que ele acredita que deve ser conhecido pela equipe, é organizada uma breve apresentação (geralmente de 5 a 15 minutos). Tentamos fazer isso uma vez por semana. Os assuntos tendem a variar, desde novos recursos e maneiras de lidar com problemas complexos que surgiram recentemente, através de abordagens de teste / codificação, componente reutilizável, até conversas sobre os fundamentos do aplicativo e sua refatoração.

Alguns assuntos são mencionados em conversas semelhantes em toda a empresa. Descobrimos maneiras bastante eficientes de estimular o compartilhamento de conhecimento. É muito mais fácil ver e lembrar de uma breve apresentação e saber onde procurar documentação adicional ou a quem procurar ajuda do que participar de sessões de treinamento muito longas e raramente realizadas ou apenas ficar sentado, lendo os documentos de capa a capa.

As conversas em toda a empresa vieram primeiro. Acabamos de adotar essa abordagem para o compartilhamento de conhecimento específico do projeto e acho que está funcionando muito bem.

A programação em pares também torna a circulação do conhecimento muito mais rápida.

Eu acho que na verdade são duas perguntas em uma - tentarei responder as duas.

1) Como reduzimos o código duplicado em uma base de código.
Isso ajuda a lembrar o benefício de fazer isso: resulta em menos erros devido à duplicação da lógica de negócios e menos código precisa ser mantido. A melhor maneira de impedir que isso aconteça é através da comunicação - conforme mencionado nas outras respostas. Concordo plenamente com a recomendação de usar as revisões de código com a ressalva de que você deve compartilhar as responsabilidades de revisão de código igualmente para espalhar o conhecimento adequadamente. Você também deve usar stand-ups diários para que os desenvolvedores frequentemente reconheçam quando alguém está tentando resolver um problema para o qual existe um código útil. Você também deve considerar o emparelhamento de código, pois aumenta o compartilhamento de conhecimento e ajuda a manter os programadores disciplinados.

Também recomendo que seus desenvolvedores fiquem o mais próximos possível, de preferência na mesma sala. Com muitos quadros compartilhados e espaço. Depois, envie-os para as refeições juntos. Quanto mais seus desenvolvedores se "vincularem", melhor eles se comunicarão.

Não concordo com a recomendação de usar um wiki ou semelhante ao código do documento. Não importa o quanto os desenvolvedores disciplinados tentem ser a documentação se afastará do código original. Uma abordagem mais eficaz seria o uso da especificação por testes de estilo de exemplo. Eles documentam o código de uma maneira que deixa claro como ele deve ser usado e seus testes falharão se alguém alterar o código sem alterar os exemplos.

Você já possui uma grande base de código com muito código duplicado; portanto, provavelmente deve trabalhar na refatoração disso. Pode ser difícil encontrar código duplicado que não foi recortado e colado. Então, em vez de fazer isso, sugiro que você analise seu histórico de alterações. Procure arquivos que frequentemente mudam ao mesmo tempo. Provavelmente isso indicará problemas com o encapsulamento, se não indicar o código duplicado real e vale a pena limpá-lo de qualquer maneira. Se você também pode analisar seu histórico de correção de bugs com relação às alterações de código, poderá encontrar pontos de acesso específicos, onde as correções são frequentemente necessárias. Analise esses pontos de acesso e provavelmente descobrirá que muitos deles se devem à lógica de negócios duplicada, que um desenvolvedor mudou apenas em um local, sem perceber que precisava mudar duas vezes.

2) Como devemos abordar a criação de widgets, componentes, bibliotecas, etc compartilhados, que podem ser usados ​​em outros projetos ?
Nesse caso, você não deve tentar quebrar a lógica de negócios, mas compartilhar um código de estrutura útil. Esse pode ser um equilíbrio complicado, pois o custo de criação e manutenção de um conjunto de componentes compartilhados pode ser bastante grande e pode ser difícil prever em quais casos vale a pena fazê-lo. A abordagem que eu sugiro aqui é uma regra de três greves. Não se preocupe em escrever um código semelhante duas vezes, mas quando precisar fazê-lo pela terceira vez refatorá-lo em um componente compartilhado. Nesse ponto, você pode ter certeza razoável de que será útil e ter uma boa idéia dos requisitos mais amplos do componente. Obviamente, a comunicação entre desenvolvedores é vital aqui.

Considere criar o maior número possível de código aberto do seu componente compartilhado. Não é uma lógica de negócios, portanto não dará muita vantagem aos seus concorrentes, mas significa que você receberá revisores e mantenedores extras gratuitamente.

IMMO a chave não é documentação ou ferramentas, a chave é COMUNICAÇÃO. Mais de 10 desenvolvedores não são muitas pessoas, algumas coisas que melhoram essa comunicação:

• programação em pares: com duas pessoas, há mais mudanças que uma das duas sabe que o problema já foi resolvido em outra parte do projeto e a reutiliza.

• Propriedade do código coletivo: todas as pessoas trabalham com as diferentes partes dos sistemas, assim é muito mais fácil saberem que algo já foi feito em outra parte do projeto, para mim é uma prática fundamental em equipe.

• Reserve um tempo para trabalhar em projetos horizontais: por exemplo, uma sexta-feira ou duas em um mês, e os desenvolvedores nesse período poderão trabalhar em seus próprios projetos que tenham alguma aplicabilidade no projeto da sua empresa. Dessa forma, os desenvolvedores podem escrever bibliotecas e componentes reutilizáveis, às vezes seu código já existe, mas precisa de alguma limpeza e documentação.

• Organize palestras e workshops: reserve um tempo para palestras e workshops para desenvolvedores, os desenvolvedores podem falar sobre suas bibliotecas ou talvez você possa refatorar workshops e pegar código duplicado e remover a duplicação, criando um componente reutilizável.

A documentação provavelmente é necessária, mas é apenas uma pequena parte do que você precisa: melhore a comunicação dentro de sua equipe.

Que tal usar um mecanismo de pesquisa local como o Lucene (ou algo mais específico para o código-fonte) para indexar seu código? Quando alguém começa a escrever uma nova classe ou uma nova função (por exemplo), ele deve tentar (como política interna) algumas pesquisas antes de escrever seu próprio código. Dessa forma, você pode evitar muitas comunicações e confiar em bons comentários, métodos e nomes de classes. Eu me pego fazendo isso com os mecanismos de pesquisa de código aberto disponíveis na internet: não sei quem escreveu o que ou o que é o nome de um método ou classe, mas com algumas pesquisas ou sinônimos, sempre encontro o que preciso.

Você precisa de uma ferramenta que ajude seus desenvolvedores a fazê-lo de maneira integrada. Se seus desenvolvedores descobrirem quanto tempo eles podem economizar reutilizando os trechos de código (não apenas em termos de escrita do código, mas obviamente para garantia de qualidade, integração etc.), ajudados por uma ferramenta eficiente, fácil de usar e diretamente integrados ao ambiente de desenvolvimento, eles vão orar para que você adote essa ferramenta!

Tenha cuidado para que muitas vezes a realização de bibliotecas para reutilização de código não resulte em uma enorme vantagem (elas tendem a se tornar muito poderosas e grandes ...); em vez disso, gostaria de focar em trechos simples, ou seja, poucas linhas de código que resolvem uma tarefa específica de maneira eficaz.

Dessa maneira, você pode forçar o uso de diretrizes e práticas recomendadas, fornecendo exemplos reais que podem ser usados ​​diretamente pelos programadores.

Existem várias ferramentas para o gerenciamento de trechos, eu recomendo este: http://www.snip2code.com .

(Isenção de responsabilidade: sou um dos fundadores do Snip2Code e estava - junto com meus co-fundadores - em sua mesma mentalidade há algum tempo: foi por isso que decidimos iniciar este projeto, que reúne todos os recursos que eu acima, compartilhamento de trechos entre uma equipe, integração em IDEs como Visual Studio, Eclipse, IntelliJ, Notepad ++ etc.)