Analyze and document code using GitHub Copilot

GitHub Copilot can help you understand and document a codebase by generating explanations and documentation. In this exercise, you use GitHub Copilot to analyze a codebase and generate documentation for the project.

This exercise should take approximately 20 minutes to complete.

IMPORTANT: To complete this exercise, you must provide your own GitHub account and GitHub Copilot subscription. If you don’t have a GitHub account, you can sign up for a free individual account and use a GitHub Copilot Free plan to complete the exercise. If you have access to a GitHub Copilot Pro, GitHub Copilot Pro+, GitHub Copilot Business, or GitHub Copilot Enterprise subscription from within your lab environment, you can use your existing GitHub Copilot subscription to complete this exercise.

Before you start

Your lab environment must include the following: Git 2.48 or later, .NET SDK 9.0 or later, Visual Studio Code with the C# Dev Kit extension, and access to a GitHub account with GitHub Copilot enabled.

If you’re using a local PC as a lab environment for this exercise:

For help configuring your local PC as your lab environment, open the following link in a browser: Configure your lab environment resources.
For help enabling your GitHub Copilot subscription in Visual Studio Code, open the following link in a browser: Enable GitHub Copilot within Visual Studio Code.

If you’re using a hosted lab environment for this exercise:

For help enabling your GitHub Copilot subscription in Visual Studio Code, paste the following URL into a browser’s site navigation bar: Enable GitHub Copilot within Visual Studio Code.
To ensure that the .NET SDK is configured to use the official NuGet.org repository as a source for downloading and restoring packages:

Open a command terminal and then run the following command:
```
  dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org
```

Exercise scenario

You’re a developer working in the IT department of your local community. The backend systems that support the public library were lost in a fire. Your team needs to develop a temporary solution to help the library staff manage their operations until the system can be replaced. Your team chose GitHub Copilot to accelerate the development process.

Your colleague has developed an initial version of the library application, but due to time constraints, they haven’t had a chance to document the code. You need to analyze the codebase and create documentation for the project.

This exercise includes the following tasks:

Set up the library application in Visual Studio Code.
Use GitHub Copilot to explain the library application codebase.
Use GitHub Copilot to create a README.md file for the library application.

Set up the library application in Visual Studio Code

Your colleague has developed an initial version of the library application and has made it available as a .zip file. You need to download the zip file, extract the code files, and then open the solution in Visual Studio Code.

Use the following steps to set up the library application:

Open a browser window in your lab environment.
To download a zip file containing the library application, paste the following URL into your browser’s address bar: GitHub Copilot lab - Analyze and document code

The zip file named AZ2007LabAppM2.zip will be downloaded to your lab environment.
Extract the files from the AZ2007LabAppM2.zip file.

For example:
1. Navigate to the downloads folder in your lab environment.
2. Right-click AZ2007LabAppM2.zip, and then select Extract all.
3. Select Show extracted files when complete, and then select Extract.
Open the extracted files folder, then copy the AccelerateDevGHCopilot folder to a location that’s easy to access, such as your Windows Desktop folder.
Open the AccelerateDevGHCopilot folder in Visual Studio Code.

For example:
1. Open Visual Studio Code in your lab environment.
2. In Visual Studio Code, on the File menu, select Open Folder.
3. Navigate to the Windows Desktop folder, select AccelerateDevGHCopilot and then select Select Folder.
In the Visual Studio Code SOLUTION EXPLORER view, expand the solution to show the following solution structure:
- AccelerateDevGHCopilot
  - src
    - Library.ApplicationCore\
    - Library.Console\
    - Library.Infrastructure\
  - tests
    - UnitTests\
Ensure that the solution builds successfully.

For example, in the SOLUTION EXPLORER view, right-click AccelerateDevGHCopilot, and then select Build.

You may see some Warnings, but there shouldn’t be any Errors.

Use GitHub Copilot to explain the library application codebase

GitHub Copilot can help you to understand an unfamiliar codebase by generating explanations at the solution, file, and code line levels.

Analyze code using prompts in the Chat view

GitHub Copilot’s Chat view includes a chat-based interface that allows you to interact with GitHub Copilot using natural language prompts. When evaluating an existing codebase for the first time, you can create prompts that generate an explanation at the workspace or project level, or at the code block or code line level. To assist you in specifying the context of your prompt, GitHub Copilot provides chat participants, chat variables, and slash commands.

Use chat participants in your prompts to invoke a domain-specific expert. Experts provide the most accurate responses.
Use chat variables in your prompts to include specific context. Context helps GitHub Copilot generate more relevant responses.
Use slash commands in your prompts to invoke specific actions or to set the intent of your prompt.

Use the following steps to complete this section of the exercise:

Ensure that the AccelerateDevGHCopilot solution is open in Visual Studio Code.
Open GitHub Copilot’s Chat view.

To open the Chat view, select the Toggle Chat button at the top of the Visual Studio Code window.

You can also open the Chat view using the Ctrl+Alt+I keyboard shortcut.
In the Chat view, enter a prompt that uses the #codebase chat variable to include the full context of the codebase when generating a description of your code.

For example, enter the following prompt in the Chat view:
```
 #codebase describe this project
```
Use chat variables, such as #codebase, to include specific context in your prompt. Context helps GitHub Copilot generate more relevant responses.
Take a minute to compare GitHub Copilot’s response with the actual project files.

You should see a response that describes all of the projects included in the solution:
- Library.ApplicationCore
- Library.Console
- Library.Infrastructure
- UnitTests
Use the SOLUTION EXPLORER view to expand the project folders.
Take a moment to review the project files.
Enter a prompt in the Chat view that asks how to publish your codebase to a private GitHub repository.

For example, enter the following prompt in the Chat view:
```
 @github #codebase What's the easiest way to publish my current codebase to a private GitHub repo from within Visual Studio Code? 
```
Use chat participants, such as @github, to assign a domain expert for your prompt. Domain experts help GitHub Copilot generate accurate responses.

NOTE: GitHub Copilot considers your chat history and the code files you have open in Visual Studio Code when constructing a context for your prompt and generating a response.
Open the Program.cs file and examine the code.
Enter a prompt in the Chat view that generates an explanation of the Program.cs file.

For example, enter the following prompt in the Chat view:
```
 /explain #codebase Explain the Program.cs file
```
Use slash commands, such as /explain, to specify the intent of your prompt. Communicating your intent helps GitHub Copilot understand the type of response that it needs to generate. The list of available slash commands may vary depending on your environment and the context of your chat.
Take a minute to review the detailed response generated by GitHub Copilot.

You should see a response that includes an overview and a breakdown that explains how the file is used within the application.
Close the Program.cs file.

Improve chat responses by adding context

GitHub Copilot uses context to generate relevant responses.

Opening files in the code editor is one way to establish context, but you can also add files to the Chat context using drag-and-drop operations or by using the Add Context button in the Chat view.

Use the following steps to complete this section of the exercise:

Expand the Library.Infrastructure project, and then expand the Data folder.
Use a drag-and-drop operation to add the following files from the SOLUTION EXPLORER view to the Chat context: JsonData.cs, JsonLoanRepository.cs, and JsonPatronRepository.cs.

GitHub Copilot uses the Chat context to understand the code files that are relevant to your prompt. You can add files to the Chat context using drag-and-drop operations, or you can use the Add Context button in the Chat view.

Instead of adding individual files manually, you can let Copilot find the right files from your codebase. This approach can be useful when you don’t know which files are relevant to your question, but it does slow down the response time. To let Copilot find the right files automatically, add #codebase in your prompt.
Enter a prompt in the Chat view that generates an explanation of the data access classes.

For example, enter the following prompt in the Chat view:
```
 /explain Explain how the data access classes work
```
Take a couple minutes to read through the response.

You should see a response that describes each of the data access classes (JsonData, JsonLoanRepository, and JsonPatronRepository) and how they work together to manage data access in the application. Key methods, such as LoadData, SaveLoans, and SavePatrons, should be mentioned in the response.
Take a minute to examine the JSON data files that are used to simulate library records.

The JSON data files are located in the src/Library.Console/Json folder.

The data files use ID properties to link entities. For example, a Loan object has a PatronId property that links to a Patron object with the same ID. The JSON files contain data for authors, books, book items, patrons, and loans.

NOTE: Notice that Author names, book titles, and patron names have been anonymized for the purposes of this training.

Build and run the application

Running the application helps you understand the user interface, key features of the application, and how app components interact.

Use the following steps to complete this section of the exercise:

Ensure that you have the Solution Explorer view open.

The Solution Explorer is a dedicated view added to Visual Studio Code’s primary sidebar by the C# Dev Kit extension. It provides a structured, solution-centric view of your .NET application that’s similar to the Solution Explorer in the Visual Studio IDE. It’s more informative and organized than the plain folder/file tree that the built-in Explorer view.
To run the application, right-click Library.Console, select Debug, and then select Start New Instance.

If the Debug and Start New Instance options aren’t displayed, ensure that you’re using the Solution Explorer view and not the Explorer view.

The following steps guide you through a simple use case.
When prompted for a patron name, type One and then press Enter.

You should see a list of patrons that match the search query.

NOTE: The application uses a case-sensitive search process.
At the “Input Options” prompt, type 2 and then press Enter.

Entering 2 selects the second patron in the list.

You should see the patron’s name and membership status followed by book loan details.
At the “Input Options” prompt, type 1 and then press Enter.

Entering 1 selects the first book in the list.

You should see book details listed, including the due date and return status.
At the “Input Options” prompt, type r and then press Enter.

Entering r returns the book.
Verify that the message “Book was successfully returned.” is displayed.

The message “Book was successfully returned.” should be followed by the book details. Returned books are marked with Returned: True.
To begin a new search, type s and then press Enter.
When prompted for a patron name, type One and then press Enter.
At the “Input Options” prompt, type 2 and then press Enter.
Verify that first book loan is marked Returned: True.
At the “Input Options” prompt, type q and then press Enter.
Stop the debug session.

Create the project documentation for the README file

Readme files provide project contributors and stakeholders with essential information about a code repository. They help users understand the purpose of the project, how to use it, and how to contribute. A well-structured README file can significantly improve the usability and maintainability of a project.

You need a README file that includes the following sections:

Project Title: A brief, clear title for the project.
Description: A detailed explanation of what the project is and what it does.
Project Structure: A breakdown of the project structure, including key folders and files.
Key Classes and Interfaces: A list of key classes and interfaces in the project.
Usage: Instructions on how to use the project, often including code examples.
License: The license that the project is under.

In this section of the exercise, you’ll use GitHub Copilot to create project documentation and add it to a README.md file.

Use the following steps to complete this section of the exercise:

Add a new file named README.md to the root folder of the AccelerateDevGHCopilot solution.
Open the Chat view, and select the Ask agent mode.

To generate project documentation for your README file, enter the following prompt:


 #codebase I need you to generate the contents of a README.md file that I can use for the current code repository. Use "Library App" as the project title. The README file should include the following sections: Description, Project Structure, Key Classes and Interfaces, Usage, License. Format all sections as raw markdown. Use a bullet list with indents to represent the project structure. Do not include ".gitignore" or the ".github", "bin", and "obj" folders. I want add the suggested content to the README.md file that's open in the editor.

NOTE: Using multiple prompts, one for each section of the README file would produce more detailed results. A single prompt is used in this exercise to simplify the process.

Review the response to ensure each section is formatted as markdown.

You can update sections individually to provide more detailed information or if they aren’t formatted correctly. You can also copy GitHub Copilot’s response to the README file and then make corrections directly in the markdown file.
Copy the suggested documentation, and then paste it into the README.md file.

To copy the entire response, scroll to the bottom of the response, right-click in the empty space to the right of the “thumbs-up” icon, and then select Copy
Format the README.md file as needed.

You can update the settings for GitHub Copilot to enable markdown formatting, then use GitHub Copilot to help you update sections of the README.md file.

When you’re finished, you should have a README.md file that includes each of the specified sections, with an appropriate level of detail.

Summary

In this exercise, you learned how to use GitHub Copilot to analyze and document a codebase. You used GitHub Copilot to generate explanations for the project structure, key classes, and data access classes. You also used GitHub Copilot to create a README.md file for the project.

Clean up

Now that you’ve finished the exercise, take a minute to ensure that you haven’t made changes to your GitHub account or GitHub Copilot subscription that you don’t want to keep. If you made any changes, revert them now.