Preferisci esempi sulla documentazione. È un problema comportamentale?

L'abitudine di fare affidamento sugli esempi non ha nulla di sbagliato: per te, è solo il modo più veloce per ottenere la tua risposta. Inoltre, gli esempi sono visivi. È più semplice analizzare visivamente un esempio piuttosto che leggere i paragrafi di testo ed estrarre le informazioni necessarie.

Esempio:

In order to list the products, one should use Index action of the Products controller, given that GET is the only possible verb here (see [Affecting products] for more information about the actions used to create, modify and delete the products from the database).

In order to obtain detailed information about a specific product, append its unique identifier to the end of the URI. If you want to get the list of every product available, don't append anything. You may also use filters, as described in the [REST filters for selecting data] section of the manual. Note that the list of products is limited to one thousand items. [Pagination] can be used to walk through the entire list, given that each page is still limited to one thousand items.

You may also want to force the service to refresh the quantities in stock. This is done by setting the refresh-quantities to one.

è dettagliato, ma noioso e appena leggibile. Il fatto che sia necessario seguire i collegamenti rende le cose ancora peggiori. Se aggiungiamo alcuni esempi, diventa molto più facile da capire:

GET Products/Index/
GET Products/Index/12345/
GET Products/Index/?skip=100&take=20
GET Products/Index/?category=12
GET Products/Index/?price=0..39.90
GET Products/Index/?category=12&skip=100&take=20

Il fatto che tu usi solo gli esempi potrebbe essere un problema. Non smettere semplicemente di usare gli esempi, ma ricorda che una volta ottenuta l'idea, una documentazione più dettagliata può essere d'aiuto. Ad esempio, l'esempio sopra riportato non mostra che l'elenco di prodotti è limitato a 1 000: devi leggere la documentazione per questo.

Quando sai che dovresti leggere la documentazione?

Ogni volta che l'API o la libreria non si comportano come previsto. Ad esempio, prendi l'esempio e fai:

GET Products/Index/?skip=6000&take=3000

Per qualche ragione, restituisce meno di 3 000 articoli, mentre hai più di ventimila prodotti nel tuo database. Qui, l'API non si comporta come tu , quindi è un buon momento per leggere la documentazione dettagliata.

Le informazioni fornite dalla documentazione rientrano in tre categorie:

• Recipe.
• Riferimenti.
• Conoscenza esperta.

Le ricette o l'esempio costituiscono un ponte tra il dominio problematico e le funzionalità del software. Il riferimento descrive completamente alcune funzionalità ed è utile se si desidera adattare una ricetta a un caso specifico.

(Conoscenze esperte mappano i concetti del dominio problematico ai concetti di documentazione, è utile se i concetti possono essere espressi in più maniere o se gli utenti del software non sono esperti nel campo.)

How do I break this bad habit as a programmer or am I over thinking? Any wisdom from fellow programmers is appreciated.

Non penso che la tua abitudine sia cattiva. Quando impari un'API, ti viene in primo luogo un'idea di quali problemi possono essere risolti e quali metodologie sono fornite con l'aiuto di Ricette (i tuoi esempi). La documentazione di riferimento ti aiuta quindi a mettere a punto le metodologie in casi particolari.

Gli esempi sono documentazione. Non penso che sia male da una presa di familiarità con il punto di vista delle API. Se è l'unica documentazione che guardi, può essere un problema. La maggior parte degli esempi risparmia sul controllo degli errori che può portare a un codice troppo fragile se non si torna indietro e si raccolgono i pezzi mancanti dalla documentazione di riferimento.

Diverse persone imparano meglio in modi diversi. Alcune persone sono come te e imparano meglio dagli esempi. Alcune persone sono come me e imparano meglio dalla documentazione dettagliata. Avere entrambi nella documentazione sembra coprire abbastanza bene la maggior parte degli sviluppatori. Parla con un insegnante, loro possono dirti una mezza dozzina di modi in cui le persone imparano.