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

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 eles não têm prática e não gostam de fazer isso. Escrever uma visão geral do código leva tempo que você não pode gastar em codificação, e o benefício inicial para um projeto é sempre maior se você puder dizer "Apoiamos todas as três variantes de codificação" em vez de "Nós realmente explicações claras do nosso código! " A noção de que tal documento atrairá mais desenvolvedores para que, a longo prazo, mais código seja escrito não seja exatamente estranho para eles, mas é percebido como uma aposta incerta; Esse texto realmente fará a diferença entre conseguir um colaborador ou não? Se eu continuar codificando agora , certamente faremos isso.

Um documento de visão geral de código também pode fazer com que as pessoas se sintam defensivas; é difícil descrever decisões de nível mais alto sem sentir a necessidade de justificá-las, e com muita frequência as pessoas tomam decisões sem uma razão que "soa boa o suficiente" quando escritas de fato. Há também um efeito relacionado ao já mencionado: uma vez que a atualização do texto para se adequar ao código em mudança 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, isso se transformará em um risco.

A verdade seca e dura?

A documentação não é feita porque os projetos podem passar sem isso.

Até mesmo projetos de código aberto frequentemente enfrentam strong concorrência. A maioria desses projetos não começa com grandes ombros, eles começam com uma ideia brilhante, muitas vezes uma idéia brilhante de um homem.

Como tal, eles não podem pagar o tempo e os custos de contratação de documentadores humanos, mesmo se eles se oferecerem para cooperar de graça. Um projeto documentado, na verdade, passou por várias iterações iniciais primeiro. Geralmente começa com 1 a 3, talvez 5 pessoas escrevendo sua ideia original e mostrando ao mundo como uma prova de conceito. Se a ideia for boa, então os "seguidores" podem adicionar, eles tendem a pedir extensões, novas opções, traduções ... Neste 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 tem que "pensar grande e distante" e planejar expansões e assim por diante. Ele pode muito bem se tornar o projeto "evangelista" e às vezes também "gerente de projetos" (outras vezes são pessoas diferentes). Esse é um passo necessário para elevar o projeto, da prova de conceito a uma realidade estabelecida no setor.

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

Um projeto dinâmico e em crescimento seria retardado e a documentação ficaria muito atrasada em relação ao código, ao mesmo tempo em que seria aprimorada, para implementar traduções, opções, plug-in de gerentes ...

O que geralmente acontece é:

1. Um breve documento introdutório é feito, 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. Expecially 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 escrever um liner descrevendo suas funções, os parâmetros são "auto" documentados também e o todo está ligado ao seu código e assim evitam a documentação " desyncing "e atrasado behing desenvolvimento.
4. Na maioria das vezes, um fórum é criado. É uma poderosa mídia social na qual os usuários finais e programadores podem falar uns com os outros (e entre seus pares, possivelmente em subfóruns "somente desenvolvedores"). Isso permite que muito conhecimento surja aos poucos e seja consolidado por perguntas frequentes e HOWTOs feitos pela comunidade (leia-se: sem pesar sobre a equipe de desenvolvedores).
5. Em projetos realmente grandes, um wiki também é produzido. Eu declaro "grandes projetos" porque eles são freqüentemente aqueles com seguidores suficientes para criar um wiki (um desenvolvedor faz) e então realmente o preenchem além dos "esqueletos" (a comunidade faz).

Os documentos de visão geral descritos por você são raros, mesmo em projetos comerciais. Eles exigem esforço extra com pouco valor para os desenvolvedores. Também 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 uma boa documentação do usuário. A documentação do desenvolvedor, se existir, provavelmente não será atualizada para refletir as alterações no código.

Qualquer projeto bem organizado terá uma árvore de diretórios que é relativamente autoexplicativa. Alguns projetos documentarão essa hierarquia e / ou as razões pelas 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 ter um conhecimento limitado do código ao redor. Você nunca deve ter que entender toda a base de código para fazer isso. Se você tem uma ideia razoável do tipo de função que é quebrada, é sempre possível navegar na hierarquia de diretórios rapidamente.

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

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

Veja meu artigo Adicionando o SHA-2 a tinyca para um exemplo de como tais mudanças podem ser feitas. Eu tenho uma compreensão extremamente limitada do código usado para gerar a interface.

Are there things like these and I'm missing them? Things that do the same job as I am describing?

Existe um excelente livro chamado A Arquitetura de Aplicações Open Source que fornece descrições detalhadas de uma variedade de projetos de software de código aberto. No entanto, não tenho certeza se isso preenche exatamente o papel que você está imaginando, porque acredito que seu público-alvo primário seja o desenvolvedor que procura padrões a serem seguidos ao criar seus próprios aplicativos, e não novos contribuidores para os projetos apresentados no livro. (embora tenha certeza de que poderia ser útil lá).

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

A documentação exige manutenção e tempo para se manter atualizado. Quanto mais volumosa a documentação, mais ela demora. E a documentação que não está em sincronia 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 em primeiro lugar. 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 as alterações no código valem as contribuições de desenvolvedores extras pode ou não trazer?

O código de envio ganha. Reduzir a quantidade de esforço investida em outras coisas além do código de embarque pode fazer com que o código seja enviado com mais frequência e ser mais provável de ser lançado antes de ficar sem recursos.

Isso não significa que as coisas além do frete sejam importantes. A documentação agrega valor ao projeto e, com um projeto grande o suficiente, o custo de interconexão de adicionar outro desenvolvedor pode ser muito maior do que adicionar um documentador. E, conforme observado, a documentação pode aumentar o investimento no projeto (tornando mais fácil a participação de novos programadores).

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

A documentação de uma base de código é uma forma de meta-trabalho. Você pode gastar muito tempo escrevendo documentos sofisticados descrevendo uma base de código que não faz muito valor, ou você pode gastar tempo fazendo coisas que os consumidores de sua base de código querem e fazendo com que sua base de código tenha valor.

Às vezes, dificultar as coisas torna melhor quem faz a tarefa. Seja devido a um maior grau de comprometimento com o projeto (gastando horas após horas aprendendo a arquitetura), ou devido ao viés de habilidade (se você já é um especialista em tecnologia relacionada, a velocidade será mais rápida, então a barreira da falta de tal documentação é menos importante: assim, mais especialistas se juntam à equipe e menos iniciantes).

Por fim, por razões citadas acima, os desenvolvedores atuais provavelmente serão especialistas na base de código. Escrever tal documentação não ajuda os eles a entenderem muito a base de código, pois eles já possuem o conhecimento, isso só ajuda outros desenvolvedores. Grande parte do desenvolvimento de código aberto é baseado em "coçar uma coceira" que o desenvolvedor tem com o código: a falta de documentação que já diz o que o desenvolvedor sabe raramente coça.

Além de ser um esforço extra , alguns projetos de código aberto estão prejudicando suas documentações propositalmente, a fim de obter freelancers empregos para seus mantenedores (para implementar algo, ou para realizar treinamentos). Não só eles não têm visão geral do código, mas sua API e tutoriais são ruins ou faltam muitas coisas.

Apenas para nomear um bastante popular: bluez. Boa sorte em encontrar um bom tutorial, além de procurar por dispositivos próximos.