Préférez les exemples à la documentation. Est-ce un problème de comportement?

Chaque fois que je rencontre une nouvelle API ou un nouveau langage de programmation ou même de simples pages de manuel Linux , je les ai toujours (depuis que je m'en souvienne) évitées et au lieu de cela, je comptais paresseusement sur des exemples pour mieux comprendre de nouveaux concepts.

Inconsciemment, j'évite la documentation / API chaque fois que ce n'est pas simple ou cryptique ou simplement ennuyeux. Cela fait des années que j'ai commencé à programmer et maintenant je sens que j'ai besoin de me ressaisir car je me rends compte maintenant que je cause plus de dégâts en m'abstenant de lire la documentation cryptique / difficile car elle est toujours un million de fois meilleure que les exemples officiels la documentation a plus de couverture que tout autre exemple. Même après avoir réalisé que les exemples devraient être traités comme une valeur «ajoutée» au lieu de la source «principale» d'apprentissage.

Comment puis-je briser cette mauvaise habitude en tant que programmeur ou ai-je une réflexion excessive?

L'habitude de s'appuyer de préférence sur des exemples n'a rien de mal: pour vous, c'est juste le moyen le plus rapide d'obtenir votre réponse. De plus, les exemples sont visuels. Il est plus facile d'analyser visuellement un exemple plutôt que de lire des paragraphes de texte et d'extraire les informations dont vous avez besoin.

Exemple:

Afin de lister les produits, il faut utiliser l' Indexaction du Productscontrôleur, étant donné que GETc'est le seul verbe possible ici (voir [Affecter les produits] pour plus d'informations sur les actions utilisées pour créer, modifier et supprimer les produits de la base de données).

Afin d'obtenir des informations détaillées sur un produit spécifique, ajoutez son identifiant unique à la fin de l'URI. Si vous souhaitez obtenir la liste de tous les produits disponibles, n'ajoutez rien. Vous pouvez également utiliser des filtres, comme décrit dans la section [Filtres REST pour la sélection des données] du manuel. Notez que la liste des produits est limitée à mille articles. [Pagination] peut être utilisé pour parcourir toute la liste, étant donné que chaque page est toujours limitée à mille éléments.

Vous pouvez également forcer le service à actualiser les quantités en stock. Pour ce faire, définissez le refresh-quantitiessur un.

est détaillé, mais ennuyeux et à peine lisible. Le fait que vous ayez besoin de suivre des liens aggrave encore les choses. Si nous ajoutons quelques exemples, cela devient beaucoup plus facile à comprendre:

Produits GET / Index /
Produits GET / Index / 12345 /
Produits GET / Index /? Skip = 100 & take = 20
Produits GET / Index /? Category = 12
Produits GET / Index /? Price = 0..39.90
Produits GET / Index /? catégorie = 12 & sauter = 100 & prendre = 20

Le fait que vous n'utilisiez que les exemples peut poser problème. N'arrêtez pas clairement d'utiliser les exemples, mais n'oubliez pas qu'une fois que vous avez eu l'idée, une documentation plus détaillée peut vous aider. Par exemple, l'exemple ci-dessus ne montre pas que la liste des produits est limitée à 1 000: vous devez lire la documentation pour cela.

Quand savez-vous que vous devez lire la documentation?

Chaque fois que l'API ou la bibliothèque ne se comporte pas comme prévu. Par exemple, vous prenez l'exemple et faites:

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

Pour une raison quelconque, il renvoie moins de 3 000 articles, alors que vous avez plus de vingt mille produits dans votre base de données. Ici, l'API ne se comporte pas comme vous attendiez, il est donc un bon moment pour lire la documentation détaillée.

Les informations fournies par la documentation se répartissent en trois catégories:

• Recette.
• Référence.
• Connaissances expertes.

Des recettes ou des exemples jettent un pont entre le domaine problématique et les fonctionnalités du logiciel. La référence décrit complètement certaines fonctionnalités et est utile si vous souhaitez adapter une recette à un cas spécifique.

(Les connaissances d'experts mappent les concepts du domaine problématique aux concepts de la documentation, il est utile que les concepts puissent être exprimés de plusieurs manières ou si les utilisateurs du logiciel ne sont pas des experts dans le domaine.)

Comment puis-je rompre cette mauvaise habitude en tant que programmeur ou suis-je en train de réfléchir? Toute sagesse de collègues programmeurs est appréciée.

Je ne pense pas que votre habitude soit mauvaise. Lorsque vous apprenez une API, vous avez d'abord une idée des problèmes qui peuvent être résolus et des méthodologies fournies à l'aide de Recipes (vos exemples). La documentation de référence vous aide ensuite à affiner les méthodologies à des cas particuliers.

La documentation en est un exemple. Je ne pense pas que ce soit mauvais du fait de se familiariser avec le point de vue de l'API. Si c'est la seule documentation que vous regardez, cela peut être un problème. La plupart des exemples lésinent sur la vérification des erreurs, ce qui peut conduire à un code trop fragile si vous ne revenez pas chercher les pièces manquantes dans la documentation de référence.

Différentes personnes apprennent mieux de différentes manières. Certaines personnes sont comme vous et apprennent mieux à partir d'exemples. Certaines personnes sont comme moi et apprennent mieux grâce à une documentation détaillée. Les deux dans la documentation semblent assez bien couvrir la plupart des développeurs. Parlez à un enseignant, ils peuvent vous expliquer une demi-douzaine de façons d'apprendre.