Recherche et compréhension d’un exemple de code

Comment puis-je apprendre à partir du code sur GitHub ?

Apprendre des projets sur GitHub est un excellent moyen d’apprendre de nouvelles techniques et de trouver l’inspiration pour vos propres projets.

Toutefois, avec des millions de référentiels disponibles publiquement sur GitHub, la recherche de code qui s’applique à votre projet peut être fastidieux. Même après avoir trouvé le référentiel parfait, vous pouvez rencontrer des difficultés pour parcourir le codebase à la recherche d’exemples utiles.

Au lieu d’essayer de comprendre l’ensemble d’un projet, une meilleure approche consiste à choisir une seule fonctionnalité ou fonction et à voir comment elle fonctionne. Nous pouvons utiliser les fonctionnalités de recherche de Copilot Chat et GitHub pour localiser une fonctionnalité et la suivre dans le codebase. C'est un excellent moyen d'apprendre, car nous pouvons voir comment la fonctionnalité fonctionne du back-end au front-end.

Dans ce guide, vous allez apprendre à faire les deux en suivant un exemple de scénario : apprendre à charger et afficher des données à partir de fichiers sur un site web Jekyll. Ensuite, vous pourrez appliquer les conseils et les techniques à d’autres projets et langages de programmation.

Trouver un projet d’exemple

La première étape consiste à trouver le bon projet dont s’inspirer.

Utilisez Copilot Chat pour identifier un référentiel

Le moyen le plus rapide de trouver un projet avec du code à partir duquel vous pouvez apprendre consiste à demander à Copilot Chat de trouver des référentiels qui correspondent à vos critères.

Ouvrez Copilot Chat et démarrez une conversation à usage général. Ensuite, demandez :

Pouvez-vous trouver certains référentiels populaires qui utilisent Jekyll pour afficher des données à partir de fichiers dans le référentiel ?

Copilot retournera des liens vers des référentiels pertinents, et vous pouvez poser des questions de suivi sur les référentiels.

Souvent, Copilot terminera sa réponse par un lien vers la recherche GitHub avec plus de résultats. Ensuite, nous examinerons ces résultats.

Utilisation de la recherche pour identifier d’autres options

Si Copilot incluait un lien vers les résultats de la recherche, suivez le lien. Sinon, créez votre propre requête de recherche en suivant les étapes ci-dessous.

1. Accédez à Recherche avancée.
2. Dans la section « Options avancées », utilisez la liste déroulante « Écrit dans ce langage » pour sélectionner un langage de programmation. Pour notre site Jekyll, nous sélectionnerons « HTML ».
3. Vous pouvez également, sous « Options de référentiel », à côté de « Avec ce nombre d'étoiles », taper >150. Cela vous aidera à trouver des référentiels populaires qui sont probablement bien gérés.
4. En haut de la page, cliquez sur Recherche.

Choix d’un projet

Après avoir passé en revue les résultats de Copilot et de la recherche, nous décidons d’utiliser le référentiel github/choosealicense.com. Ce référentiel contient le code source de Choisir une licence, un site web Jekyll qui partage des informations sur les licences open source.

La page Licenses nous intéresse particulièrement, car elle affiche les licences open source les plus populaires à partir de fichiers de données.

S’orienter dans le projet

Avant d’explorer le code permettant d’afficher des fichiers de données, voyons comment se présente le référentiel en général.

Il peut être difficile de savoir par où commencer lors de la première visite d’un référentiel. Bien que chaque projet s’organise à sa manière, il existe des méthodes de documentation communes sur lesquelles nous pouvons généralement nous appuyer pour nous repérer.

Le fichier README.md

Nous vous recommandons de lire le fichier README.md, qui correspond à la page d’accueil d’un référentiel et qui s’affiche automatiquement sous la liste des fichiers. Les différents chargés de maintenance incluront des informations différentes, mais vous pouvez souvent trouver des informations sur le projet, sur la façon de le générer sur votre machine locale, ainsi que des liens vers la documentation.

Dans le référentiel github/choosealicense.com, le fichier README.md explique où se trouvent les fichiers de licence (/_licenses), les attributs que chaque licence peut posséder et comment faire fonctionner le site Web sur votre ordinateur.

Utilisation de Copilot Chat

Si le fichier README.md ne vous donne pas toutes les réponses, vous pouvez demander à Copilot de vous aider à naviguer dans le référentiel et à localiser les fonctionnalités.

Pour ouvrir Copilot Chat, cliquez sur l’icône l’icône GitHub Copilot à côté de la barre de recherche et posez votre question. Par exemple :

Quelle est la page d’arrivée principale de ce site web Jekyll ?

Lorsque vous posez des questions à Copilot sur un référentiel, il peut renvoyer les fichiers pertinents, expliquer leur rôle dans la fonctionnalité et inclure des liens.

Wiki du référentiel

Une autre source d’information possible est le wiki du référentiel, une section du référentiel spécifiquement conçue pour héberger de la documentation. Chaque référentiel sur GitHub est équipé de la fonctionnalité wiki, mais tous les référentiels ne l’utilisent pas. Pour accéder au wiki, cliquez sur l’onglet Wiki dans le référentiel.

Publications

Si le code source du référentiel est généré dans un fichier exécutable, certains chargés de maintenance du référentiel utiliseront les versions du référentiel pour publier des fichiers binaires. Vous pouvez télécharger et exécuter ces fichiers binaires pour examiner le fonctionnement de l’application lors de l’exploration du codebase, sans avoir à générer vous-même le projet.

Vous trouverez les versions d’un référentiel dans la barre latérale, à droite de la liste des fichiers et de README.md.

Documentation interne

Vous pouvez également rechercher une documentation interne dans les contenus du référentiel. Il peut s’agir d’un fichier Markdown unique ou d’un répertoire complet de fichiers Markdown. Les noms courants à rechercher sont notamment « docs », « documentation », « wiki », « ressources », « aide » et « manuel ».

Navigation dans le code source

Maintenant que nous comprenons la structure globale du référentiel, il est temps d’utiliser la recherche GitHub pour rechercher les fonctionnalités spécifiques que nous recherchons.

Lorsque vous êtes dans un référentiel et que vous cliquez dans le champ de recherche en haut de la page, GitHub ajoutera automatiquement le qualificateur de recherche repo afin que vos résultats de recherche soient limités au référentiel que vous affichez.

Pour commencer, nous avons besoin de quelque chose à rechercher. Il peut s’agir d’une chaîne de texte unique à la fonctionnalité que nous examinons, ou nous pouvons examiner la source HTML de la page et trouver un attribut class ou id particulier.

Dans notre exemple, nous allons rechercher le texte en haut de la page Licences, en utilisant cette requête : repo:github/choosealicense "If you’re looking for a reference table?". Cela renvoie un résultat, un fichier nommé licenses.html.

Maintenant, nous pouvons cliquer sur le résultat et approfondir ! licenses.html est la source de la page « Licences » que nous recherchions. Nous pouvons voir la chaîne que nous avons recherchée et que chacune des licences est incluse dans le code ci-dessous :

{% include license-overview.html license-id="agpl-3.0" %}

Compréhension du code source

Maintenant que nous avons trouvé le code spécifique qui nous intéresse, nous pouvons passer à l’étape de compréhension.

Demander à Copilot Chat à propos du code

Vous pouvez utiliser Copilot pour en savoir plus sur un fichier ou même sur des lignes de code spécifiques. Copilot combinera des informations sur le langage de programmation avec le contexte du référentiel pour répondre à vos questions en détail.

Demandons à Copilot d’expliquer ce qui se passe à la ligne 11, avec la balise {% include %}. Cliquez sur le numéro de ligne. Ensuite, à droite de la ligne, cliquez sur . Dans la fenêtre de conversation, demandez :

Que se passe-t-il dans cette ligne ?

Copilot expliquera que la ligne inclut le fichier license-overview.html et transmet "agpl-3.0" en tant que license-id à afficher.

Lecture des commentaires

Les commentaires sont des annotations lisibles par l’homme que vous pouvez utiliser pour comprendre le code et qui ne sont pas exécutées. Ils sont généralement délimités par des caractères tels que // ou /*.

Il existe plusieurs types de commentaires à rechercher :

• Ligne : commentaires à ligne unique qui décrivent ce qu’effectue une ligne particulière
• Bloc : commentaires multilignes qui peuvent décrire ce qu’effectue une fonction ou un fichier entier
• Fichier : commentaire de bloc au début d’un fichier, fournissant une vue d’ensemble de cette partie particulière du codebase

Recherche de fonctions dans les références de langage de programmation

Chaque langage de programmation aura une référence en ligne, expliquant chaque aspect du langage.

Si vous utilisez un moteur de recherche pour rechercher le langage de programmation et la fonction, vous devez trouver un lien vers la page de référence de cette fonction.

Pour notre exemple, la recherche de jekyll include dans un moteur de recherche doit renvoyer la documentation « Inclut » dans la documentation Jekyll. Si nous poursuivons la lecture de la documentation de Jekyll, nous pouvons voir que les licences elles-mêmes sont une collection dans le répertoire _licenses.

Pour résumer ce que nous avons appris : le fichier licenses.html inclut /_includes/license-overview.html pour chaque licence affichée. Le fichier /_includes/license-overview.html correspond au license-id fourni à une licence dans la collection /_licenses et affiche les détails.

Expérimentation de petites modifications

Si vous êtes en mesure d’exécuter le projet localement sur votre ordinateur, un excellent moyen d’apprendre consiste à apporter de petites modifications pour voir ce qui se passe.

Vous pouvez commencer par modifier du texte, puis passer à des modifications plus importantes, par exemple en expérimentant la façon dont les fonctions et les fichiers interagissent les uns avec les autres.

Essayez de trouver le fichier license-overview.html dans le répertoire _includes, puis de modifier l’affichage de la licence ou d’expérimenter le chargement de la licence à partir de la collection.

Vous pouvez modifier les métadonnées au début de l’un des fichiers de licence, modifier les attributs affichés dans license-overview.html, ou même essayer d’ajouter votre propre attribut. Une fois votre modification effectuée, vous pouvez la tester en suivant les instructions du fichier README.md pour l’afficher dans votre navigateur.

Application de ce que nous avons appris

Le référentiel github/choosealicense.com est un excellent exemple de projet Jekyll volumineux et démontre tout ce qu’il est possible de faire avec Jekyll et GitHub Pages. Pouvez-vous appliquer ce que vous avez appris de la structure du référentiel, de la façon dont il utilise les collections et de la manière dont il inclut les données de licence pour générer votre propre projet ?

Étapes suivantes

Maintenant que vous comprenez le fonctionnement de l’exemple de code, vous pouvez le réutiliser dans votre propre projet. La réutilisation du code est une partie puissante du développement logiciel, mais il existe des étapes importantes à suivre pour le faire correctement et légalement. Pour obtenir un tutoriel complet, consultez Réutiliser le code d'autres personnes dans vos projets.