Como os projetos de código aberto podem ser bem-sucedidos sem documentação sobre seu design ou arquitetura?

11

Eu quero melhorar minhas habilidades de programação estudando projetos de código aberto famosos, mas acho que é fácil se perder apenas pulando no código-fonte.

Então, decidi ler a documentação deles sobre o design ou a arquitetura (como diagramas UML) para ter uma idéia geral da organização do código primeiro. Para minha surpresa, no entanto, não consigo encontrar nenhuma documentação arquitetural para grandes projetos de código aberto, como Hibernate, Spring, ASP.NET MVC, Rails, etc.

Então comecei a me perguntar: como um projeto de código aberto pode ser bem-sucedido se os desenvolvedores iniciantes não têm documentação de arquitetura / design para ler ou se o gerente de projeto acabou de abrir o código-fonte, mas fechou a documentação?

open-source documentation asp.net-mvc

— TomCaps
fonte

3

"a maioria"? Você pode apoiar isso com estatísticas concretas? Quantos você leu? Quantos existem? Quantos não possuíam documentação apropriada? Se você não possui números, remova palavras como "a maioria" e substitua-as por fatos reais com base no que você realmente encontrou. Além disso, coloque "I" em maiúscula ao se referir a si mesmo.

— S.Lott

@ S.Lott Desculpe pelo subjetivo "mais". Eu sou um novato na indústria de software. Eu estou tentando procurar documentos que eu tinha ouvido falar durante a faculdade (como UML Diagram, Flow chart, Brief Design Doc, Detaled Design Doc, etc) para os projetos mencionados no site do projeto ou no repositório de códigos, mas sem sorte, apenas para encontrar algum documento do guia do usuário. Você pode me ensinar uma maneira comum de pesquisar seus documentos de desgin / arquitetura?

— TomCaps

1

Por favor remova "Muitos". Isso é tão incorreto quanto a maioria. por favor atualizar a questão para listar especificamente os projetos de código aberto específicas que carecem especificamente a documentação específica que você quer ver. Por favor, seja preciso e específico. Por favor, não seja subjetivo e vago.

— S.Lott

Eu suspeito que o motivo pelo qual o ASP.NET MVC não inclua diagramas UML seja porque o Visual Studio possa criá-los a partir do código-fonte.

— user16764

5

Você está operando sob a falsa suposição de que "empresa" é uma coisa boa. O que você aprendeu na faculdade sobre design é tudo mentira: a UML não tem absolutamente nenhum valor. Ao criar um projeto, tudo o que você precisa é de uma idéia geral do que ele deve fazer e uma vontade de jogá-lo fora, se você fizer errado da primeira vez. Para um projeto existente, basta percorrer o cabeçalho principal normalmente para obter uma boa idéia sobre o layout do projeto.

— o11c 26/08/14

10

por que um projeto de código aberto pode se tornar bem-sucedido se o desenvolvedor iniciante não tem um documento de arquitetura / design para ler?

A suposição é invariavelmente feita de que você sabe o que está fazendo e tem uma compreensão razoavelmente íntima do que está indo (e esperando) ver.

Se você olhar o código PHP da estrutura do Symfony, por exemplo, você já deve saber sobre injeção de dependência, eventos, o modelo / visão / padrão do controlador e assim por diante.

Da mesma forma, se você mergulhar no código C do kernel do linux, a suposição é que você será realisticamente competente em modularidade, sinais, processos, threads e outras coisas. Também é esperado que você tenha um talento especial para comer hexadecimal durante todo o dia e escavar através de lixões com uma pá gigante.

Os mantenedores não terão o trabalho de documentar a arquitetura, porque são coisas práticas. Na ocasião, você encontrará um esboço do que está na árvore de origem. Mais tipicamente, porém, a maneira como a árvore de origem é organizada torna as coisas auto-explicativas.

Resumindo, se você não possui nenhuma das habilidades que os mantenedores esperam que você conheça no momento em que analisa o código deles, provavelmente está pesquisando coisas que estão amplamente acima da sua nota de pagamento. Familiarize-se primeiro com os conceitos - Qual é o modelo MVC? O que é injeção de dependência? Etc. Então mergulhe.

— Denis de Bernardy
fonte

1

Embora se você olhar para as listas de discussão, o kernel do Linux tem uma extensa discussão sobre a arquitetura sempre que alguém tem um problema ou deseja mudar alguma coisa. Também existem muitos documentos escritos sobre isso - embora não na própria árvore de fontes do kernel.

— EdA-qa mort-ora-y

17

Os projetos de código aberto mais bem-sucedidos foram bem-sucedidos porque, acima de tudo, o programa era impressionante ou fez algo que nenhum outro programa poderia fazer na época. Isso não significa necessariamente que a fonte esteja bem documentada, já que os programadores que iniciaram o projeto conhecem o código suficientemente bem para não precisar dele. É uma realidade infeliz que os projetos de código aberto não precisem ser bem documentados. Ele precisa ser um bom programa ou ser um programa medíocre, mas bem documentado para que os programadores demonstrem interesse nele.

— Neil
fonte

Na minha empresa, é um procedimento obrigatório que os desenvolvedores forneçam um Documento de Projeto Detalhado antes de serem aprovados para escrever qualquer código em um projeto. Este procedimento é anormal para o projeto de código aberto?

— TomCaps

5

@TomCaps Acho que a maior razão pela qual tão poucos projetos de software livre possuem documentação extensa é bastante simples: se você está escrevendo um pequeno programa para resolver uma necessidade que você tem, é provável que, desde o desenvolvedor, você também não precise de documentação, você vai querer gastar seu tempo melhorando o programa, em vez de escrever uma documentação que não garante a utilidade de ninguém (e se o projeto nunca for usado por ninguém além do desenvolvedor?). Não é uma prática recomendada, mas muitos projetos de software livre têm pouco tempo de desenvolvedor.

— Jeff Welling

5

@TomCaps: Este procedimento é anormal para a maioria das empresas que eu sei ...

— Treb

1

A maioria dos projetos de código aberto não são empresas. Você está pensando no que acontece quando há um projeto que estou sendo pago para construir, com prazo e orçamento. Se você tem um monte de gente codificando para suprir uma necessidade que eles têm ou por diversão e não há orçamento ou cliente, você não tem esse tipo de coisa.

— Elin

1

@ TomCaps - qualquer pessoa que escreva software de código aberto pode fazer exatamente o que quiser. Alguns projetos (por exemplo, a família Apache) têm regras e diretrizes para qualquer pessoa que comprometa código e, às vezes, isso inclui padrões de duplicação etc. Também questionaria o valor de um "documento de design detalhado", pois isso invariavelmente o trancará em um design físico que (em minha experiência pessoal) geralmente é abaixo do ideal. Uma descrição detalhada de "o que" o programa deve fazer deixa o desenvolvedor livre para otimizar a implementação e aplicar estratégias criativas à solução.

— James Anderson

12

Como os desenvolvedores de código aberto geralmente são talentosos e também escolhem projetos em sua área de especialização, eles já têm "documentação" dentro de seus crânios. Com pouco exagero, é necessária uma documentação completa apenas se você não tiver um desses: o)

Para ser sincero, eu realmente não leio "documentação" quando enfrento uma base de código desconhecida. Uma introdução rápida, talvez alguns esboços conceituais e direto para o código! Experimente, tente pequenas alterações. Funciona perfeitamente para código bem projetado. Se eu enfrentar uma bagunça horrível, a melhor maneira de aprendê-las é refatorar pouco a pouco para melhorar a clareza (idealmente com a ajuda do teste de unidade).

Razões adicionais podem ser as raízes orgânicas simples desses projetos. A arquitetura é então uma visão bastante evoluída nas mentes dos desenvolvedores do que a entidade "documentada" declarada.

— MaR
fonte

8

A razão pela qual esses documentos geralmente não existem é bastante simples: os programadores gostam de programar, não escrevem documentação. Especialmente em projetos de código aberto, com os quais os desenvolvedores costumam contribuir durante seu tempo livre / lazer.

Basicamente, escrever documentação não é divertido. E se eles não são pagos por isso, quem quer gastar seu tempo livre fazendo algo que não é divertido?

— GrandmasterB
fonte

Alguns grandes projetos de código aberto (GCC, kernel do Linux, Firefox, Qt, ....) têm a maioria (ou uma parte significativa) de seus colaboradores pagos para trabalhar (em período integral ou meio período) no projeto. Assim, mesmo quando pago para o software livre, eles não escrever uma grande quantidade de documentação

— Basile Starynkevitch