Como posso aprender com o código no GitHub?
Aprender com projetos no GitHub é uma ótima maneira de aprender novas técnicas e encontrar inspiração para seus projetos.
No entanto, com milhões de repositórios disponíveis publicamente no GitHub, encontrar o código que se aplica ao seu projeto pode ser uma tarefa e tanto. Mesmo após encontrar o repositório perfeito, pode ser difícil navegar pela base de código para encontrar exemplos úteis.
Em vez de tentar entender um projeto inteiro, uma abordagem melhor é escolher um só recurso ou função e ver como ele funciona. Podemos usar o Copilot Chat e a funcionalidade de pesquisa do GitHub para localizar um recurso e segui-lo na base de código. Essa é uma ótima maneira de aprender, pois podemos ver como o recurso funciona desde o back-end até o front-end.
Neste guia, você aprenderá a fazer ambos seguindo um cenário de exemplo: aprender a carregar e exibir dados de arquivos em um site Jekyll. Em seguida, poderá aplicar as dicas e técnicas a outros projetos e linguagens de programação.
Localizando um projeto de exemplo
A primeira etapa é localizar o projeto certo com o qual aprender.
Use o Copilot Chat para identificar um repositório
A maneira mais rápida de localizar um projeto com código com o qual você pode aprender é solicitar ao Copilot Chat que localize repositórios que correspondam aos seus critérios.
Abra o Copilot Chat e inicie um chat de uso geral. Em seguida, pergunte:
Você pode encontrar alguns repositórios populares que usam Jekyll para exibir dados de arquivos no repositório?
O Copilot retornará links para repositórios relevantes e você poderá fazer perguntas adicionais sobre os repositórios.
Muitas vezes, o Copilot encerra sua resposta com um link para uma pesquisa do GitHub com mais resultados. Em seguida, examinaremos esses resultados.
Usando a pesquisa para identificar mais opções
Se o Copilot incluiu um link para resultados de pesquisa, siga o link. Caso contrário, forme sua consulta de pesquisa seguindo as etapas abaixo.
- Navegue até Advanced search.
- Na seção "Advanced options", use a lista suspensa "Written in this language" para selecionar uma linguagem de programação. Para nosso site Jekyll, selecionaremos "HTML".
- Opcionalmente, em "Repositories options", ao lado de "With this many stars", digite
>150. Isso ajudará você a encontrar repositórios populares que provavelmente são bem mantidos. - Na parte superior da página, clique em Search.
Tip
Podemos restringir ainda mais os resultados da pesquisa adicionando tópicos e texto à consulta de pesquisa. Por exemplo, topic:jekyll "blog" retornaria repositórios que o proprietário classificou como relacionados ao Jekyll e que têm a palavra "blog" no nome ou na descrição. Para ver uma lista de tópicos populares, confira Tópicos no GitHub.
Escolhendo um projeto
Depois de examinar os resultados do Copilot e da pesquisa, decidimos usar o repositório github/choosealicense.com. Esse repositório contém o código-fonte de Choose a License, um site Jekyll que compartilha informações sobre licenças de software livre.
Estamos particularmente interessados na página Licenses, que exibe licenças populares de software livre de arquivos de dados.
Orientando-se dentro do projeto
Antes de examinarmos o código para exibir arquivos de dados, vamos nos orientar no repositório em geral.
Pode ser difícil saber por onde começar quando você visita um repositório pela primeira vez. Embora cada projeto se organize de maneira individual, há métodos comuns de documentação nos quais geralmente podemos confiar para nos orientarmos.
O arquivo README.md
É sempre uma boa ideia ler o arquivo README.md, que é a primeira página de um repositório e é renderizado automaticamente abaixo da lista de arquivos. Diferentes mantenedores incluirão informações diferentes, mas geralmente você pode encontrar informações sobre o projeto, como compilá-lo em seu computador local e links para a documentação.
No repositório github/choosealicense.com, o arquivo README.md explica onde os arquivos de licença residem (/_licenses), os atributos que cada licença pode ter e como fazer com que o site seja executado no computador.
Usando o Copilot Chat
Se o arquivo README.md não fornecer todas as respostas, você poderá solicitar que o Copilot ajude a navegar no repositório e localizar funcionalidades.
Para abrir o Copilot Chat, clique no ícone do GitHub Copilot ao lado da barra de pesquisa e faça sua pergunta. Por exemplo:
Qual é a página de aterrissagem principal deste site Jekyll?
Quando você faz perguntas ao Copilot sobre um repositório, ele pode retornar os arquivos relevantes, explicar o papel que eles desempenham na funcionalidade e incluir links.
Wiki do repositório
Outra possível fonte de informações é o wikido repositório, uma seção do repositório destinada especificamente à hospedagem da documentação. Todo repositório no GitHub tem a capacidade de usar um wiki, mas nem todos os repositórios usam. Para acessar o wiki, clique na guia Wiki no repositório.
Versões
Se o código-fonte do repositório for baseado em um arquivo executável, alguns mantenedores usarão as versões do repositório para publicar arquivos binários. Você pode baixar e executar esses arquivos binários para examinar como o aplicativo funciona enquanto explora a base de código, sem precisar compilar o projeto por conta própria.
Você pode encontrar as versões de um repositório na barra lateral, à direita da lista de arquivos e do README.md.
Documentação interna
Você também pode procurar a documentação interna no conteúdo do repositório. Ela pode ser composta por um único arquivo Markdown ou por um diretório cheio de arquivos Markdown. Nomes comuns a procurar incluem "docs", "documentation", "wiki", "resources", "help" e "manual".
Navegando pelo código-fonte
Agora que entendemos a estrutura geral do repositório, é hora de usar a pesquisa do GitHub para localizar a funcionalidade específica que estamos procurando.
Quando você está em um repositório e clica no campo de pesquisa na parte superior da página, o GitHub adiciona automaticamente o qualificador de pesquisa repo para que os resultados da pesquisa sejam restritos ao repositório que você está exibindo.
Para começar, precisamos de algo para pesquisar. Pode ser uma cadeia de caracteres de texto exclusiva em relação ao recurso que estamos examinando ou podemos examinar a origem HTML da página e encontrar um atributo class ou id específico.
Em nosso exemplo, procuraremos o texto na parte superior da página de licenças usando esta consulta: repo:github/choosealicense "If you’re looking for a reference table?". Isso retorna um resultado, um arquivo chamado licenses.html.
Agora, podemos clicar no resultado e nos aprofundar! licenses.html é a fonte da página "Licences" que estávamos procurando. Podemos ver a cadeia de caracteres que pesquisamos e que cada uma das licenças está incluída com o código abaixo:
{% include license-overview.html license-id="agpl-3.0" %}
Noções básicas sobre o código-fonte
Agora que encontramos o código específico no qual estamos interessados, podemos passar a entendê-lo.
Fazendo perguntas sobre o código ao Copilot Chat
Você pode usar o Copilot para saber mais sobre um arquivo ou até mesmo sobre linhas de código específicas. O Copilot combinará informações sobre a linguagem de programação com o contexto do repositório para responder suas perguntas em detalhes.
Vamos pedir ao Copilot para explicar o que está acontecendo na linha 11, com a marca {% include %}. Clique no número da linha. Em seguida, à direita da linha, clique em . Na janela de chat, pergunte:
O que está acontecendo nessa linha?
O Copilot explicará que a linha está incluindo o arquivo license-overview.html e passando "agpl-3.0" como o license-id a ser exibido.
Tip
Se você não entender uma resposta do Copilot Chat, sempre poderá pedir para ele simplificar a resposta ou elaborar mais uma parte específica dela.
Lendo comentários
Comentários são anotações legíveis por humanos que você pode usar para entender o código. Eles não são executados. Geralmente, são delimitados com caracteres como // ou /*.
Há alguns tipos de comentários para observar:
- Linha: comentários de linha única que descrevem o que uma linha específica está fazendo
- Bloco: comentários de várias linhas que podem descrever o que uma função ou arquivo inteiro está fazendo
- Arquivo: um comentário em bloco no início de um arquivo, fornecendo uma visão geral dessa parte específica da base de código
Pesquisando funções nas referências da linguagem de programação
Cada linguagem de programação terá uma referência online, explicando cada aspecto da linguagem.
Se você usar um mecanismo de pesquisa para pesquisar a linguagem de programação e a função, deverá encontrar um link para a página de referência dessa função.
Para nosso exemplo, pesquisar por jekyll include em um mecanismo de pesquisa deve retornar a documentação de "Includes" na documentação do Jekyll. Se lermos mais sobre a documentação do Jekyll, poderemos ver que as próprias licenças são uma coleção no diretório _licenses.
Tip
Se você não encontrar uma função em uma referência de linguagem de programação, é provável que a função seja definida na própria base de código. Peça que o GitHub Copilot a localize.
Para resumir o que aprendemos: o arquivo licenses.html inclui /_includes/license-overview.html para cada licença mostrada. O arquivo /_includes/license-overview.html corresponde ao license-id fornecido a uma licença na coleção /_licenses e renderiza os detalhes.
Experimentando pequenas alterações
Se você consegue executar o projeto localmente no computador, uma ótima maneira de aprender é fazer pequenas alterações para ver o que acontece.
Você pode começar alterando o texto e, em seguida, passar a fazer alterações maiores, como experimentar como funções e arquivos interagem entre si.
Tente encontrar o arquivo license-overview.html no diretório _includes e, em seguida, fazer alterações na forma como a licença é exibida ou experimentar como a licença é carregada da coleção.
Você pode alterar os metadados no início de um dos arquivos de licença, alterar quais atributos são exibidos no license-overview.html ou até mesmo tentar adicionar seu próprio atributo. Após fazer a alteração, você pode testá-la seguindo as instruções em README.md para exibi-la no navegador.
Aplicando o que aprendemos
O repositório github/choosealicense.com é um ótimo exemplo de projeto Jekyll grande e demonstra o quanto é possível fazer com Jekyll e o GitHub Pages. Você consegue aplicar o que aprendeu com a estrutura do repositório, como ele usa coleções e a maneira como inclui os dados de licença para criar seu próprio projeto?
Próximas etapas
Agora que você entende como o código de exemplo funciona, talvez queira reutilizá-lo em seu projeto. A reutilização de código é uma parte poderosa do desenvolvimento de software, mas há etapas importantes a seguir para fazer isso de maneira correta e legal. Para ver um tutorial completo, confira Como reutilizar o código de outras pessoas nos seus projetos.