Como você acompanha as aulas e funções que sua equipe escreveu?


43

Ao trabalhar no código, enfrento muitos dos mesmos desafios que meus colegas de equipe, e escrevi algumas funções e classes úteis, e eles também. Se houver uma boa comunicação, ouvirei falar de algo maravilhoso que alguém montou e, seis meses depois, quando precisar, talvez me lembre e chame essa função, economizando tempo. Se não me lembro, ou nunca soube, provavelmente reinventarei a roda.

Existe uma prática específica de documentar esse tipo de coisa? Como você os torna fáceis de encontrar?

Se sua equipe não possui essa documentação, como descobrir se sua roda já existe?

EDITAR:

Todas, exceto uma das respostas até agora, tratam de uma situação ideal, então deixe-me resumir essas soluções: documentação e comunicação; wikis, reuniões stand-up, etc. Tudo isso é ótimo, mas eles dependem de programadores que têm tempo (e habilidades) para escrever a documentação e participar das reuniões, tomar notas e lembrar de tudo.

A resposta mais popular até agora (de Caleb) é a única que poderia ser usada por um programador que é incapaz de documentação e reuniões, e faz apenas uma coisa: programação. Programar é o que um programador faz, e sim, um ótimo programador pode escrever documentação, testes de unidade, etc., mas vamos ser sinceros - a maioria de nós prefere programar a documentar. Sua solução é aquela em que o programador reconhece código reutilizável e o extrai para sua própria classe ou repositório ou qualquer outra coisa, e pelo fato de ser isolado, torna-se acessível e facilita a curva de aprendizado para usá-lo ... e isso foi realizado pela programação.

De certa forma, vejo assim: acabei de escrever três funções, e me ocorre que alguém deveria saber sobre elas. Eu poderia documentá-los, escrevê-los, anunciá-los em uma reunião etc. - o que posso fazer, mas não é a minha força - ou ... Posso extraí-los para uma classe, dar um nome a ele, fazê-los funcionar como uma caixa preta e cole-a onde os outros arquivos de classe vão. Em seguida, um breve email anunciando que é fácil. Outros desenvolvedores podem escanear o código e entendê-lo melhor do que uma função isolada usada em código que não entendem completamente - esse contexto é removido.

Eu gosto disso porque significa que ter um conjunto de arquivos de classe bem nomeados, com métodos bem nomeados, é uma boa solução que é realizada por uma boa programação. Não requer reuniões e suaviza a necessidade de documentação detalhada.

Existem mais idéias nesse sentido ... para desenvolvedores isolados e pressionados pelo tempo?


5
Eu expandiria a questão para fazer uma escala maior, talvez em uma empresa com mais de 100 funcionários, como você faz o mesmo. Quais práticas recomendadas podem ser feitas para evitar a duplicação do trabalho realizado anteriormente?
Asaf

1
@Asaf - Suspeito que a resposta correta dependa do tamanho da população - o que funciona para uma loja para 5 pessoas não funciona para 50 e o que funciona para 50 não funciona para 500. As respostas para todos seriam bem-vindas.
Dan Pichelman

3
Esta é uma grande pergunta!
Rocklan

4
Lei de Conway : "organizações que projetam sistemas ... são constrangidas a produzir projetos que são cópias das estruturas de comunicação dessas organizações".
Mark Rushakoff

2
@nathanhayfield: essa é uma solução que pode funcionar para 1 desenvolvedor e, até certo ponto, para 2, mas não para 20 ou 100. E mesmo quando trabalho sozinho, prefiro separar funções auxiliares tematicamente.
Doc Brown

Respostas:


29

Bibliotecas. Frameworks. Controle de versão.

Se você tem código reutilizável, a última coisa que você deseja é que diferentes membros da equipe copiem o código-fonte no projeto. Se eles fizerem isso, é provável que eles mudem um pouco aqui e mexam um pouco ali, e logo você terá dezenas de funções ou métodos que têm o mesmo nome, mas que funcionam cada um de maneira um pouco diferente. Ou, talvez mais provavelmente, o autor original continuará refinando o código para corrigir bugs, torná-lo mais eficiente ou adicionar recursos, mas o código copiado nunca será atualizado. O nome técnico para isso é uma enorme bagunça .

A solução certa é extrair esse material reutilizável de qualquer projeto para o qual você o construiu e colocá-lo em uma biblioteca ou estrutura em seu próprio repositório de controle de versão. Isso facilita a localização, mas também desencoraja fazer alterações sem levar em consideração todos os outros projetos que possam estar usando. Você pode considerar ter várias bibliotecas diferentes: uma para código bem testado que provavelmente não será mais alterado, outra para coisas que parecem estáveis, mas que não foram exaustivamente testadas e revisadas, e uma para adições propostas.


5
Eu também gostaria de recomendar um conjunto muito completo de testes de regressão para a biblioteca reutilizável. Mesmo que a mudança pareça inofensiva, alguém pode estar dependendo desse comportamento.
Bobson

2
Eu pensei que o termo técnico era BBOM .
precisa saber é o seguinte

2
Sua resposta parece razoável à primeira vista e, em pequena e média escala, é verdade, mas também vi o lado sombrio de uma diretiva "não copie". Se você possui equipes diferentes para produtos diferentes, com termos de licença diferentes, ciclos de vida diferentes e contratos de manutenção diferentes, a última coisa que você deseja é associar os diferentes produtos a uma biblioteca caseira de trechos de código que não atendem aos requisitos de manutenção . Bibliotecas para esse tipo de necessidade cenário para ter alta qualidade, e às vezes a sua ainda mais effient para uma equipe para copiar o código e ..
Doc Brown

3
@ Caleb: mantenha a calma, leia minha postagem completamente. O que quero dizer é: copiar código de outro lugar, ajustá-lo e integrá-lo à biblioteca de equipes não o leva necessariamente ao "caminho da perdição". Quando você tem duas bibliotecas com funcionalidade sobreposta e duas equipes das quais cada uma é responsável por manter sua biblioteca, a situação não é tão ruim. Isso não é perfeito, uma vez que uma equipe pode fazer algum trabalho e a outra também, mas às vezes a vantagem de que essas equipes permanecem independentes supera o dobro do trabalho.
Doc Brown

1
@DocBrown Em algumas situações, torna-se necessário copiar o código, mas isso deve ser uma decisão consciente e não algo que você é forçado a fazer devido à maneira pela qual o código foi compartilhado.
Caleb

13

Uma abordagem para isso é configurar um Wiki para esse fim e escrever alguns documentos de alto nível sobre quais componentes reutilizáveis ​​você possui, como solucionou um problema etc.

A parte difícil é fazer com que todos na sua equipe mantenham esse Wiki constantemente. Mas qualquer outro tipo de documentação sofre com o mesmo problema.

Alguns dos seus códigos também podem ser bons o suficiente para serem colocados em uma biblioteca reutilizável. Isso também facilita a localização do código novamente mais tarde.


5
Um wiki não é o caminho certo para disseminar código. É uma ótima maneira de se comunicar sobre código, mas (veja minha resposta) você não quer que as pessoas copiem nada maior que um trecho de um wiki e colem no seu projeto.
Caleb

@ Caleb a comunicação é a parte mais difícil
jk.

@jk - Os problemas de comunicação são agravados se você não tem o controle de origem mencionado no C
Jeffo

3
@ Caleb: a pergunta do OP não era sobre a disseminação do código, a questão era sobre a comunicação e a localização mais tarde.
Doc Brown

@DocBrown Novamente, os wikis são ótimos para se comunicar, e é provavelmente por isso que ferramentas como o GitHub foram incorporadas. Mas o que facilita a localização de código não é que ele é mencionado em um wiki, é que ele é mantido em um local conhecido. Isso pode ser um wiki, mas se estamos falando de código que as pessoas realmente usarão (em comparação a vários trechos que ilustram uma solução), deve ser uma biblioteca de algum tipo, algo que pode ser edificado, testado e que pode ser incorporado sem multiplicar o número de locais em que mais cedo ou mais tarde precisará ser atualizado.
Caleb

7

Estar em uma empresa com 700 funcionários, em equipes que variam de 2 a 20 pessoas, eis a minha experiência.

No nível da equipe

Temos "reuniões stand-up" todos os dias por cerca de 15 a 20 minutos. Podemos compartilhar rapidamente conhecimentos comuns como "Eu fiz essa função ontem, é muito difícil".

Também temos um wiki por projeto. O que significa que podemos compartilhar informações (técnicas) sobre o que é feito no projeto, incluindo classes / funções personalizadas que foram incorporadas.

No nível da agência

No nível da agência, temos 4 ferramentas:

  • Outro wiki. Está lá principalmente para nos fornecer informações sobre hardware e outras coisas, mas às vezes as usamos para compartilhar informações técnicas a serem revisadas antes de colocá-las no nível da empresa.
  • Reuniões semanais. Eles são principalmente para saber o progresso de cada equipe / projeto, mas como somos principalmente entusiastas da tecnologia, podemos trazer coisas legais.
  • Lista de discussão. Temos uma correspondência com todos na agência. Muitas coisas legais / coisas divertidas / coisas úteis passam por lá.
  • Repositório VCS. Cada agência tem seu repositório pessoal, onde temos pequenos projetos, principalmente módulos que usamos em diferentes projetos.

No nível da empresa

No nível da empresa, é mais organizado.

O wiki "nível de agência" é realmente parte do wiki da empresa.

E o wiki é então dividido com base em tecnologias. Assim, qualquer um pode melhorar, pesquisar e basicamente dar uma vida ao wiki.

Também existem listas de discussão disponíveis nas quais podemos assinar. Qualquer pessoa na agência pode se inscrever, e a maioria das pessoas segue pelo menos uma ou duas tecnologias; na verdade, a maioria das pessoas segue de 5 a 10 delas.

E o VCS é obviamente o melhor sistema de compartilhamento de código.

Conclusão

Para resumir, não há uma solução clara. O compartilhamento de conhecimento sempre foi um grande problema e provavelmente permanecerá. Existem muitas soluções para criar bases de conhecimento , e provavelmente uma pode ser adequada à sua conta. No entanto, algumas pessoas estão tentando obter uma KB ainda melhor, pois as soluções atuais nem sempre são muito inteligentes.


Eu sinto que a conclusão deve dizer nada mais do que "wiki, wiki, wiki, wiki, wiki", mas com uma observação séria, boa resposta, um wiki interno pode ser bom para detalhar detalhes de nível mais alto ou idade de uso, para não mencionar apenas ser pesquisável economiza bastante tempo.
RhysW

6

Bem, tudo se resume à comunicação.

Os wiki são ótimos e você definitivamente deve instalar e usar um. Uma boa intranet interna de programadores é boa se as pessoas lêem e atualizam, então você está realmente falando de um problema de pessoas lá. Você pode sugerir reuniões semanais de "atualização da equipe" nas quais todos se reúnem e fornece uma visão geral do trabalho que está acontecendo. Os líderes técnicos (pelo menos!) Devem estar se reunindo e conversando sobre o que cada equipe está fazendo. As sessões informais "Brown Bag" são ótimas, agende-as na hora do almoço e faça as pessoas conversarem.

Você também precisa de uma maneira de compartilhar código, empacotá-lo, versioná-lo e distribuí-lo. As coisas seriam mais fáceis se você tiver um repositório de código-fonte realmente bem gerenciado, organizado bem em pastas "comuns" e de projeto.

Se nada disso estiver sendo feito, converse com seu chefe, explique como isso beneficiará a empresa e sugira um caminho a seguir :)


1
Gostaria de avançar um pouco mais o conceito "comum" em sua resposta.
Jeffo

4

As sessões de revisão de código podem ajudar. Se sua equipe se reúne regularmente para discutir o que foi desenvolvido, a pessoa que apresentou uma solução pode mostrar aos outros como usá-la. Se alguém abordar um ponto em que está se mantendo, outros membros da equipe poderão propor uma abordagem que aumente a reutilização dos componentes existentes.


1
Depois, 4 anos e 600 funções depois, quando você quer se lembrar daquela função que foi criada há algum tempo? Parte do problema do OP era tentar lembrar de todas as coisas que haviam sido criadas, embora isso seja bom no início, ele não se sustentará por um período de talvez um mês ou dois.
RhysW

2

A melhor maneira de lidar com algo assim é ter uma estrutura de repositório que possua algumas convenções simples, para que eu saiba, como programador, se existe uma função doXYZ, mais ou menos onde eu deveria procurá-la. Esteja você usando espaços para nome, diretórios, módulos, plug-ins, pacotes, o que for, seu código deve ser modular, para que funções que façam a mesma coisa ou acessem as mesmas fontes de dados estejam no mesmo local.


0

Idealmente, deve haver pelo menos uma outra pessoa, além do autor, fazendo uma revisão de código em cada check-in. O processo de revisão de código pode ajudar a atenuar o problema de muitos métodos duplicados que estão sendo registrados. Obviamente, você está limitado pelo conhecimento dos revisores.

TL; DR: Revisões de código para cada check-in.


2
Não entenda. Você vai jogar fora o código testado e funcionando apenas porque parece uma duplicata em uma revisão de código? A questão era como evitar escrever o código duplicado em primeiro lugar. Uma sessão como a resposta de @ daenyth parece melhor.
adrianm

Se um revisor me dissesse que estou adicionando código que duplica a funcionalidade, e verifiquei que eles estavam certos, diabos, sim, eu descartaria o código idiota. (Eu provavelmente também verificar se a minha aplicação é melhor, e se assim for, ver se eu poderia refatorar a outra implementação em vez de adicionar um novo.)
Carolyn
Ao utilizar nosso site, você reconhece que leu e compreendeu nossa Política de Cookies e nossa Política de Privacidade.
Licensed under cc by-sa 3.0 with attribution required.