Por que não há visões gerais de código para projetos de código aberto? [fechadas]

Existem projetos de código aberto muito complexos por aí, e para alguns deles acho que poderia dar algumas contribuições, e gostaria de poder, mas a barreira à entrada é muito alta por um único motivo: para alterar uma linha de código por vez. grande projeto, você precisa entender tudo.

Você não precisa ler todo o código (mesmo se você ler, não será suficiente) e entender tudo o que cada linha faz e por quê, porque o código provavelmente é modularizado e compartimentado, portanto existem abstrações, mas mesmo assim, é necessário obter uma visão geral do projeto para saber onde estão os módulos, onde um módulo faz interface com outro, o que exatamente cada módulo faz e por quê e em quais diretórios e arquivos estão acontecendo essas coisas.

Estou chamando essa visão geral de código , como o nome de uma seção que os projetos de código aberto poderiam ter no site ou na documentação que explica seu código para pessoas de fora. Eu acho que isso beneficiaria os contribuidores em potencial , pois eles seriam capazes de identificar locais onde poderiam construir, os codificadores primários envolvidos, como eles poderiam, enquanto escreviam tudo, reorganizavam suas mentes e ajudavam os usuários , como eles ajudar a entender e relatar melhor os bugs que eles experimentam e talvez até se tornarem colaboradores.

Mas ainda assim eu nunca vi uma dessas "visões gerais de código". Por quê? Existem coisas como essas e estou sentindo falta delas? Coisas que fazem o mesmo trabalho que eu estou descrevendo? Ou é uma ideia completamente inútil, pois todos, exceto eu, podem entender projetos com milhares de linhas de código facilmente?

Porque é um esforço extra para criar e manter esse documento, e muitas pessoas não entendem os benefícios associados.

Muitos programadores não são bons escritores técnicos (embora muitos sejam); eles raramente escrevem documentos estritamente para consumo humano; portanto, não têm prática e não gostam de fazê-lo. Escrever uma visão geral do código leva tempo que você não pode gastar em codificação, e o benefício inicial de um projeto é sempre maior se você puder dizer "Apoiamos todas as três variantes de codificação" em vez de "Temos explicações realmente precisas do nosso código!" A noção de que esse documento atrairá mais desenvolvedores para que, a longo prazo, mais código seja escrito não é exatamente estranha para eles, mas é percebida como uma aposta incerta; este texto realmente fará a diferença entre prender um colaborador ou não? Se eu continuar codificando agora , faça isso.

Um documento de visão geral do código também pode fazer as pessoas se sentirem defensivas; é difícil descrever decisões de nível superior sem sentir a necessidade de justificá-las, e muitas vezes as pessoas tomam decisões sem um motivo que "soa bom o suficiente" quando realmente é escrito. Há também um efeito relacionado ao mencionado acima: como atualizar o texto para se adequar à alteração do código causa um esforço adicional, isso pode desencorajar mudanças radicais no código. Às vezes, essa estabilidade é uma coisa boa, mas se o código realmente precisar de uma reescrita de nível médio, ele se tornará um passivo.

A verdade seca e dura?

A documentação não é feita porque os projetos podem ficar sem ela.

Mesmo projetos de código aberto frequentemente enfrentam forte concorrência. A maioria desses projetos não começa com ombros largos, eles iniciam uma idéia brilhante, geralmente uma idéia brilhante.

Como tal, eles não podem arcar com o tempo e os custos de contratação de documentadores humanos, mesmo que tenham se oferecido para cooperar gratuitamente. Um projeto documentado, de fato, geralmente passou por várias iterações iniciais primeiro. Geralmente começa com 1 a 3, talvez 5 caras escrevendo sua nova idéia e mostrando ao mundo como uma prova de conceito. Se a idéia for boa, os "seguidores" poderão adicionar, eles tendem a começar a pedir extensões, novas opções, traduções ... Nesse ponto, o código ainda é um protótipo, geralmente com opções e mensagens codificadas.

Nem todos os projetos de código aberto vão além dessa fase, apenas aqueles que quebram a "massa crítica" necessária para atrair o interesse público. Além disso, um dos desenvolvedores iniciantes precisa "pensar grande e distante" e planejar expansões e assim por diante. Ele também pode se tornar o "evangelista" do projeto e algumas vezes também o "gerente do projeto" (outras vezes, são pessoas diferentes). Essa é uma etapa necessária para iniciar o projeto, da prova de conceito à realidade estabelecida no setor.

Mesmo assim, o gerente de projeto pode optar por não criar documentação.

Um projeto dinâmico e em crescimento ficaria mais lento e a documentação ficaria muito atrás do código enquanto está sendo aprimorada com muita dificuldade, para implementar traduções, opções, conectar gerentes ...

O que geralmente acontece é:

1. É feito um breve documento introdutório sobre o que é o projeto e para onde ele está indo (o famoso "roteiro").
2. Se possível, uma API é desenvolvida e essa é eleita como "código documentado" sobre a maior parte do código subjacente.
3. Especialmente a API, mas também o outro código, é reformatado e "PHPdoc" / "Javadoc" etc., comentários especiais são adicionados. Eles oferecem um compromisso decente entre o tempo gasto e a recompensa: mesmo um programador modesto geralmente sabe como escrever um liner descrevendo suas funções, os parâmetros também são "auto" documentados e o todo está vinculado ao seu código pertinente, evitando assim a documentação " dessincronização "e atraso no desenvolvimento.
4. Na maioria das vezes, um fórum é criado. É uma poderosa mídia social em que usuários finais e programadores podem conversar entre si (e entre seus pares, possivelmente nos sub-fóruns de "apenas desenvolvedores"). Isso permite que muito conhecimento apareça lentamente e seja consolidado pela comunidade criada (leia-se: sem pesar na equipe de desenvolvedores) FAQs e HOWTOs.
5. Em projetos realmente grandes, um wiki também é produzido. Afirmo "grandes projetos" porque geralmente são aqueles com seguidores suficientes para criar um wiki (um desenvolvedor cria) e depois o preenchem além dos "esqueletos" (a comunidade cria).

Documentos de visão geral, como você descreve, são raros, mesmo em projetos comerciais. Eles exigem um esforço extra com pouco valor para os desenvolvedores. Além disso, os desenvolvedores tendem a não escrever documentação, a menos que realmente precisem. Alguns projetos têm a sorte de ter membros que são bons em redação técnica e, como resultado, possuem boa documentação do usuário. É improvável que a documentação do desenvolvedor, se existir, seja atualizada para refletir as alterações de código.

Qualquer projeto bem organizado terá uma árvore de diretórios que é relativamente auto-explicativa. Alguns projetos documentam essa hierarquia e / ou os motivos pelos quais ela foi escolhida. Muitos projetos seguem layouts de código relativamente padrão; portanto, se você entender um, entenderá o layout de outros projetos usando o mesmo layout.

Para alterar uma linha de código, você precisa de um entendimento limitado do código ao redor. Você nunca deve entender toda a base de código para fazer isso. Se você tem uma idéia razoável do tipo de função que está com problemas, geralmente é possível navegar na hierarquia de diretórios rapidamente.

Para alterar uma linha de código, você precisa entender o método dentro do qual a linha é encontrada. Se você entender qual é o comportamento esperado do método, poderá fazer alterações corretivas ou extensões na funcionalidade.

Para idiomas que fornecem escopo, você pode refatorar métodos com escopo privado. Nesse caso, você precisará alterar os chamadores, bem como o método ou métodos de refatoração. Isso requer um entendimento mais amplo, mas ainda limitado, da base de código.

Veja meu artigo Adicionando SHA-2 ao tinyca para obter um exemplo de como essas alterações podem ser feitas. Eu tenho um entendimento extremamente limitado do código usado para gerar a interface.

Existem coisas como essas e estou sentindo falta delas? Coisas que fazem o mesmo trabalho que eu estou descrevendo?

Existe um excelente livro chamado The Architecture of Open Source Applications que fornece descrições detalhadas de uma variedade de projetos de software de código aberto de alto perfil. No entanto, não tenho certeza se ele cumpre exatamente o papel que você está imaginando, porque acredito que seu público principal se destina a desenvolvedores que procuram padrões a seguir ao criar seus próprios aplicativos, não novos contribuidores para os projetos apresentados no livro (embora eu tenha certeza de que poderia ser útil lá).

Porque há muito mais programadores de código aberto do que escritores técnicos de código aberto.

A documentação requer manutenção e tempo para se manter atualizado. Quanto mais volumosa é a documentação, mais é preciso. E a documentação que não está sincronizada com o código é pior do que inútil: engana e oculta em vez de revelar.

Uma base de código bem documentada é melhor do que uma menos documentada, mas a documentação pode facilmente demorar tanto quanto escrever o código. Portanto, sua pergunta é: é melhor ter uma base de código bem documentada ou uma base de código duas vezes maior? O custo para manter a documentação atualizada sempre que alterações de código valem as contribuições de desenvolvedores extras que ela pode ou não trazer?

O código de remessa vence. Reduzir a quantidade de esforço investido em outras coisas além do código de remessa pode fazer com que o código seja enviado com mais frequência e com maior probabilidade de envio antes que os recursos acabem.

Isso não significa que as coisas além do transporte importam. A documentação agrega valor ao projeto e, com um projeto grande o suficiente, o custo de interconexão da adição de outro desenvolvedor pode ser muito maior do que a adição de um documentador. E, como observado, a documentação pode aumentar o investimento no projeto (facilitando a participação de novos programadores).

No entanto, nada vende como sucesso: um projeto que não está funcionando ou está fazendo algo interessante raramente atrai desenvolvedores.

A documentação de uma base de código é uma forma de meta-trabalho. Você pode gastar muito tempo redigindo documentos sofisticados que descrevem uma base de código que não tem muito valor ou pode gastar tempo criando coisas que os consumidores de sua base de código desejam e que sua base de código tenha valor.

Às vezes, dificultar as coisas torna aqueles que realizam melhor a tarefa. Devido a um alto grau de comprometimento com o projeto (gastando horas e horas aprendendo a arquitetura) ou devido ao viés de habilidades (se você já é um especialista em tecnologia relacionada, acelerar a velocidade será mais rápido, portanto, a barreira da falta dessa documentação é menos importante: mais especialistas se juntam à equipe e menos iniciantes).

Finalmente, pelas razões mencionadas acima, os desenvolvedores atuais provavelmente serão especialistas na base de código. Escrever essa documentação não os ajuda a entender muito a base de código, pois eles já têm o conhecimento, apenas ajuda outros desenvolvedores. Grande parte do desenvolvimento de código-fonte aberto se baseia em "coçar uma coceira" que o desenvolvedor possui com o código: falta de documentação que já diz o que o desenvolvedor sabe que raramente coça.

Além de ser um esforço extra , alguns projetos de código aberto estão prejudicando suas documentações de propósito, a fim de conseguir trabalhos freelancers para seus mantenedores (para implementar algo ou realizar treinamentos). Além de não terem uma visão geral do código, a API e os tutoriais são ruins ou faltam muitas coisas.

Apenas para citar uma referência bastante popular: bluez. Boa sorte para encontrar um bom tutorial, além de procurar dispositivos próximos.