Sempre que me deparo com uma nova API ou linguagem de programação ou mesmo com simples páginas de manual do Linux , sempre (desde que me lembro) as evitava e, em vez disso, recorria preguiçosamente a exemplos para entender melhor os novos conceitos.
Inconscientemente, evito a documentação / APIs sempre que não é direta, enigmática ou simplesmente chata. Faz anos desde que comecei a programar e agora sinto que preciso consertar meus caminhos, pois agora percebo que estou causando mais danos ao não ler a documentação enigmática / difícil, pois ainda é um milhão de vezes melhor do que exemplos como o oficial a documentação tem mais cobertura do que qualquer exemplo existente. Mesmo depois de perceber que os exemplos devem ser tratados como valor "agregado" em vez da fonte "primária" de aprendizado.
Como quebro esse mau hábito como programador ou estou pensando demais?
fonte
a million times better than examples as the official documentation has more coverage- Nem sempre, eu encontrei ótimos recursos não documentados no passado por meio de exemplosRespostas:
O hábito de confiar na preferência em exemplos não tem nada errado: para você, é apenas a maneira mais rápida de obter sua resposta. Além disso, exemplos são visuais. É mais fácil analisar visualmente um exemplo, em vez de ler parágrafos de texto e extrair as informações necessárias.
Exemplo:
é detalhado, mas chato e mal legível. O fato de você precisar seguir os links torna as coisas ainda piores. Se anexarmos algumas amostras, fica muito mais fácil entender:
O fato de você usar apenas os exemplos pode ser um problema. Não pare claramente de usar os exemplos, mas lembre-se de que, assim que você tiver uma idéia, uma documentação mais detalhada poderá ajudar. Por exemplo, a amostra acima não mostra que a lista de produtos é limitada a 1 000: você precisa ler a documentação para isso.
Quando você sabe que deve ler a documentação?
Sempre que a API ou a biblioteca não estiver se comportando conforme o esperado. Por exemplo, você pega a amostra e faz:
Por algum motivo, ele retorna menos de 3.000 itens, enquanto você tem mais de vinte mil produtos em seu banco de dados. Aqui, a API não está se comportando como o esperado, portanto, é um bom momento para ler a documentação detalhada.
fonte
As informações fornecidas pela documentação se enquadram em três categorias:
Receitas ou exemplo fazem uma ponte entre o domínio do problema e as funcionalidades do software. A referência descreve completamente algumas funcionalidades e é útil se você deseja adaptar uma receita a um caso específico.
(O conhecimento especializado mapeia conceitos do domínio do problema para conceitos de documentação; é útil se os conceitos puderem ser expressos de várias maneiras ou se os usuários do software não forem especialistas no campo.)
Eu não acho que seu hábito seja ruim. Quando você aprende uma API, primeiro obtém uma idéia de quais problemas podem ser resolvidos e quais metodologias são fornecidas com a ajuda de Recipes (seus exemplos). A documentação de referência ajuda você a ajustar as metodologias para casos especiais.
fonte
Exemplos são documentação. Eu não acho que é ruim se familiarizar com o ponto de vista da API. Se for a única documentação que você analisa, pode ser um problema. A maioria dos exemplos economiza na verificação de erros, o que pode levar a códigos excessivamente frágeis se você não voltar e pegar as peças que faltam na documentação de referência.
fonte
Pessoas diferentes aprendem melhor de maneiras diferentes. Algumas pessoas são como você e aprendem melhor com exemplos. Algumas pessoas são como eu e aprendem melhor com a documentação detalhada. Ter ambos na documentação parece cobrir muito bem a maioria dos desenvolvedores. Converse com um professor, eles podem contar meia dúzia de maneiras pelas quais as pessoas aprendem.
fonte