How to document and comment code using AI (With examples)

Getting started with code documentation can feel overwhelming. What information should you include? How should it be structured? Effective documentation is all about finding the right balance: providing enough context for other developers to understand your functions, modules, or overall architecture without overwhelming them with unnecessary detail. Too much information can dilute the key points, creating distractions instead of clarity.

With the rise of AI, documenting code has become more accessible. Tools like ChatGPT allow you to simply paste your code and receive autogenerated comments. But are we using AI as effectively as we could? With a more intentional approach, AI can help us craft developer-friendly documentation instead of autogenerated unrelated technical documentation.

In this article, you’ll learn how to leverage AI to add just the right amount of detail, focusing on key sections that make up high-quality documentation rather than just asking AI to “document it all.” By the end, you’ll know how to guide ChatGPT to create structured, clear, and valuable code documentation that truly supports your team. We’ll also look at tools like Copilot to document your code within your editor.

Are you ready to get started with smarter, AI-powered code documentation?

When you should Generative AI to help with documenting code (and when you shouldn’t)

Using generative AI to document your code can be incredibly helpful. It can assist with summarizing modules, drafting technical specifications, and sharing summaries with your team—tasks that are crucial but often time-consuming. The good news is that AI can now support us with these efforts.

However, I don't recommend using generative AI to create your public-facing documentation. Writing documentation goes beyond automatically generating text and adding it to a README file or documentation site. It's about carefully crafting a learning experience for your audience and guiding them to use your product successfully. Clear information architecture is also essential, and from my experience, ChatGPT isn't particularly strong at creating that structure.

Ultimately, I suggest a balanced approach: combine AI with human expertise. While you should design the structure and flow of your documentation yourself, AI can help generate the content. Be sure to guide the AI by providing a clear framework. For example, every tutorial should begin with a prerequisites section and conclude with a "What did you learn?" section. For more tips on creating excellent technical documentation, check out my earlier blog post, "Tech Documentation Best Practices."

How to use AI to add comments to your code

Commenting code is a skill that requires balance. Some engineers prefer to be very detailed, adding comments to every function, while others take a more concise approach, only commenting on one or two key functions. But what's the best approach and how can we leverage AI to comment code?

First, it’s important to find the right balance when commenting your code. More importantly, your comments should capture the context behind the code, rather than just restating the function names, as this approach doesn’t add any value.

To use AI effectively for commenting, instruct ChatGPT to focus on providing context. Here's a sample prompt you can use:

Review the following code and explain its flow. Add comments only to high-value or entry functions. [insert code snippet]

Sometimes, a more active approach works better, especially when the context is fresh in your mind. Copy your code and include the context you'd like to highlight, then ask ChatGPT to refine it and insert comments:

Hey, here’s my code [insert code snippet] Here’s some context: “The “useAccountFromDb” function loads the financial accounts from the database, [...]” Can you rewrite my code context for clarity and apply it as code comments in the provided code snippet?

This method ensures you capture important context while letting ChatGPT handle the bulk of the work. Just remember to review the generated comments for accuracy.

How to use AI to document your code

One of the best practices for code documentation is to write comments as you develop the code. When the code is still fresh in your mind, it’s much easier to capture the context of a function or module.

Too often, developers finish writing their code and then realize they need to add comments to meet the requirements for submitting a pull request. In a rush, they open their code editor and add superficial comments just to check the box for submission or to meet their Definition of Done.

GitHub Copilot

With the rise of AI coding tools, it has become easier to delegate the task of writing comments. For instance, GitHub Copilot, a popular AI coding assistant, can generate meaningful comments by understanding the context of your entire project, not just the snippet you're working on. This makes it a great tool for improving the quality and completeness of your documentation.

To get started with GitHub Copilot, you'll need a GitHub account and an active Copilot subscription, as it is a paid service. Once you have both, you can install the GitHub Copilot extension in your preferred code editor. I recommend using the Visual Studio Code extension, which you can find in the Visual Studio Marketplace.

You can then open up a “GitHub Copilot Chat” using the context menu in Visual Studio Code with the shortcut CMD+SHIFT+P (Windows: CTRL+SHIFT+P)

Once you’ve opened the GitHub Copilot Chat, you can instruct it to generate code comments for your file. Be clear and specific in your instructions. For example, I requested Copilot to add a summary at the top of the file listing all functions for easier navigation, followed by detailed comments for each function. This approach enhances discoverability for functions in each file.

Next, we can refine the output by interacting with Copilot whenever we’re unsatisfied with the results. For example, I instructed Copilot to add additional descriptions for each function at the top of the file to provide even more context. You can keep interacting with GitHub Copilot to adjust the comments until you’re happy with the outcome.

Finally, we can ask to apply the structure we like to all files within my API module. This is a handy hack for quickly generating code comments for all files without having to re-instruct Copilot on the desired structure.

And that’s it! 

How to use AI to improve your existing documentation

If you already have existing documentation, you can use AI to enhance its quality. In a previous blog post about best practices for technical documentation, I explained the key sections that contribute to a great tutorial. Let’s recap those here:

• Overview: This section sets the context before starting the tutorial.

• Prerequisites: Few things are more frustrating than following a tutorial only to realize you're missing a dependency or other required components that weren’t mentioned.

• Step-based instructions: Provide simple, clear instructions focusing on one task at a time.

• Summary: Include a “What did you learn?” section to reinforce key information developers should remember. 

• What’s next: Guide developers on their next steps to keep them on the right learning path.

Once you've outlined this structure, you can use ChatGPT to enhance your tutorials. Provide it with the structure you want and feed it your existing documentation, asking it to improve the content following this format.

However, explicitly ask ChatGPT to flag missing information, as AI can sometimes generate fake requirements or instructional steps to fill documentation gaps. I’ve seen this happen when using AI to improve documentation—it may create nonexistent details. While ChatGPT is a great tool, it can’t solve every problem. Always review the output carefully!

Further tips for writing great tech documentation

Creating great technical documentation begins with designing a solid structure. This structure should act as a learning path for your users. Start with an introductory or onboarding section, move on to an easy-to-understand feature, and as users become familiar with multiple features, guide them toward combining those features for more advanced use cases. Well-structured documentation helps users grasp core concepts, progressively build their knowledge, and confidently explore more powerful capabilities.

If you are unsure how to start crafting the information architecture for your documentation, look at the Divio Documentation structure. This documentation system organizes content into four categories:

1. Tutorials: These are step-by-step guides that walk users through new features. They are always learning-focused and offer a hands-on, handholding approach.
2. How-To Guides: Guides are the opposite of tutorials. They are problem-oriented and help users solve specific issues. Unlike tutorials, how-to guides often skip over basic instructions and are aimed at users who already have some familiarity with the product.
3. Explanations: Explanations provide the "why" behind features, helping users understand the context, purpose, and benefits of using certain functionalities.
4. Reference: The reference guide is information-oriented because it lets you look up detailed information about SDK functions, API endpoints, or input parameters.
   

(Source: https://docs.divio.com/documentation-system/)

Conclusion

Documenting code can feel overwhelming initially. However, with the help of AI, you can simplify the process of code documentation. You can streamline code commenting and documentation using tools like ChatGPT and GitHub Copilot. 

Remember, AI is a powerful tool, but it works best when paired with your expertise. Rather than simply asking it to auto-generate code comments or documentation, guide it to capture context and follow a clear structure. By taking an intentional approach, you can use AI to save time and significantly improve the quality of your documentation.

Now it’s your turn: use these strategies to harness AI to craft developer-friendly documentation.