Prefira exemplos à documentação. É um problema comportamental?

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?

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:

Para listar os produtos, deve-se usar a Indexação do Productscontrolador, pois esse GETé o único verbo possível aqui (consulte [Afetando produtos] para obter mais informações sobre as ações usadas para criar, modificar e excluir os produtos do banco de dados).

Para obter informações detalhadas sobre um produto específico, anexe seu identificador exclusivo ao final do URI. Se você deseja obter a lista de todos os produtos disponíveis, não anexe nada. Você também pode usar filtros, conforme descrito na seção [Filtros REST para seleção de dados] do manual. Observe que a lista de produtos é limitada a mil itens. [Paginação] pode ser usado para percorrer a lista inteira, pois cada página ainda está limitada a mil itens.

Você também pode forçar o serviço a atualizar as quantidades em estoque. Isso é feito configurando-o refresh-quantitiescomo um.

é 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:

Produtos GET / Índice /
Produtos GET / Índice / 12345 /
Produtos GET / Índice /? Skip = 100 & take = 20
Produtos GET / Índice /? Categoria = 12
Produtos GET / Índice /? Preço = 0..39,90
Produtos GET / Índice /? category = 12 & pular = 100 & levar = 20

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:

Produtos GET / Índice /? Skip = 6000 & take = 3000

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.

As informações fornecidas pela documentação se enquadram em três categorias:

• Receita.
• Referência.
• Conhecimento especializado.

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.)

Como quebro esse mau hábito como programador ou estou pensando demais? Qualquer sabedoria dos colegas programadores é apreciada.

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.

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.

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.