Preferisci esempi rispetto alla documentazione. È un problema comportamentale?

Ogni volta che mi imbatto in una nuova API o in un linguaggio di programmazione o anche in semplici pagine man di Linux , le ho sempre (da quando ricordo) evitate e invece ho pigramente fatto affidamento su esempi per comprendere nuovi concetti.

Inconsciamente, evito la documentazione / API ogni volta che non è semplice o criptico o semplicemente noioso. Sono passati anni da quando ho iniziato a programmare e ora mi sento come se avessi bisogno di riparare i miei modi poiché ora mi rendo conto che sto causando più danni astenendomi dalla lettura di documenti criptici / difficili in quanto è ancora un milione di volte migliore degli esempi come ufficiale la documentazione ha una copertura maggiore di qualsiasi altro esempio. Anche dopo aver realizzato che gli esempi dovrebbero essere trattati come valore "aggiunto" anziché come fonte "primaria" per l'apprendimento.

Come faccio a spezzare questa cattiva abitudine come programmatore o sto pensando troppo?

L'abitudine di affidarsi preferibilmente agli 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 paragrafi di testo ed estrarre le informazioni necessarie.

Esempio:

Per elencare i prodotti, si dovrebbe usare l' Indexazione del Productscontroller, dato che qui GETè l'unico verbo possibile (consultare [Influenzare i prodotti] per ulteriori informazioni sulle azioni utilizzate per creare, modificare ed eliminare i prodotti dal database).

Per ottenere informazioni dettagliate su un prodotto specifico, aggiungere il suo identificatore univoco alla fine dell'URI. Se desideri ottenere l'elenco di tutti i prodotti disponibili, non aggiungere nulla. È inoltre possibile utilizzare i filtri, come descritto nella sezione [Filtri REST per la selezione dei dati] del manuale. Si noti che l'elenco dei prodotti è limitato a mille articoli. [Impaginazione] può essere utilizzato per scorrere l'intero elenco, dato che ogni pagina è ancora limitata a mille elementi.

È inoltre possibile forzare il servizio ad aggiornare le quantità disponibili. Questo viene fatto impostando refresh-quantitiessu uno.

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

OTTIENI prodotti / Indice /
OTTIENI prodotti / Indice / 12345 /
OTTIENI prodotti / Indice /? Skip = 100 & take = 20
OTTIENI prodotti / Indice /? Categoria = 12
OTTIENI prodotti / Indice /? Prezzo = 0..39.90 OTTIENI
prodotti / Indice /? categoria = 12 & saltare = 100 & prendere = 20

Il fatto che tu usi solo gli esempi può essere un problema. Non smettere chiaramente di usare gli esempi, ma ricorda che una volta che hai avuto l'idea, una documentazione più dettagliata può aiutare. Ad esempio, l'esempio sopra non mostra che l'elenco dei prodotti è limitato a 1 000: per questo è necessario leggere la documentazione.

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:

OTTIENI Prodotti / Indice /? Skip = 6000 & take = 3000

Per qualche motivo, restituisce meno di 3000 articoli, mentre nel database sono presenti oltre ventimila prodotti. Qui, l'API non si comporta come si aspettava, quindi è un buon momento per leggere la documentazione dettagliata.

Le informazioni fornite dalla documentazione rientrano in tre categorie:

• Ricetta.
• Riferimento.
• Conoscenze specialistiche.

Ricette o esempi creano 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.

(Le conoscenze degli esperti associano i concetti del dominio problematico ai concetti della documentazione, è utile se i concetti possono essere espressi in diverse maniere o se gli utenti del software non sono esperti nel campo.)

Come posso spezzare questa cattiva abitudine come programmatore o sto pensando troppo? Ogni saggezza dei colleghi programmatori è apprezzata.

Non penso che la tua abitudine sia cattiva. Quando apprendi un'API, ti viene prima 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 speciali.

Esempi sono la documentazione. Non penso che sia male dal punto di vista della conoscenza dell'API. Se è l'unica documentazione che guardi, allora può essere un problema. La maggior parte degli esempi risparmia sul controllo degli errori che può portare a un codice troppo fragile se non torni indietro e raccogli 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, possono dirti mezza dozzina di modi in cui le persone imparano.