Documenting code with AI
1. Documenting code with AI
Welcome back! In this next video, we will explore some practical examples of how AI models can assist with one of the more time-consuming and often overlooked aspects of software development: code documentation.2. AI-Powered docstring generation
There are many aspects in which an AI model can help us automate documentation and summarization in a development workflow. One of them is docstring generation.3. AI-Powered docstring generation
Sometimes, when we give the model a simple prompt like “Write a docstring for this function”, it responds with just a brief description. For instance, let’s take a look at a sales_trend() function which determines the overall sales trend from a series of daily sales. In this case, the model will return a short docstring that only describes the function at a high level.4. AI-Powered docstring generation
An effective prompt strategy is to break the task down into the specific components we expect the docstring to include. For example, we could use instead: “Generate a docstring for this function that includes: A simple explanation of what the function does. A description of each parameter and its type. A description of the return value and its type“. The model effectively generates the full docstring.5. AI-Powered docstring generation
By specifying the steps, we can customize the docstring as much as we need. For example, by adding extra elements such as an example section.6. Adapting to documentation styles
Docstrings follow different standards and styles, and an AI model will (in principle) adopt whichever standard we specify. For example, we might say, "Generate a docstring for this function using Google style" or "Use NumPy style".7. Adapting to documentation styles
Now let's say our sales_trend() function shown before is part of the SalesAnalyzer class. We can also generate the full API documentation for the entire class. A possible prompt for it could be: “Analyze this class and generate an API reference entry including method names, descriptions, and parameter details”. As with the docstring, we can also choose the desired API style. For example, markdown or Sphinx-compatible format.8. Summarizing code into READMEs
Another potential task is processing code changes, such as generating a README file based on the class implementation.9. Summarizing code into READMEs
Let’s now generate the README file for the SalesAnalyzer class. One possible prompt could be: “Generate a README file in Markdown that explains the SalesAnalyzer class and its methods. Include a sample code snippet to help users analyze the sales trend over a random period”10. Commit messages from code diffs
We can also use AI models to analyze code changes and create descriptive commit messages.11. Commit messages from code diffs
As we can observe in this example, AI models can assist with this task, especially when provided with the diff between the previous and updated code. A commonly used command to generate this difference is git diff.12. Automating release notes
Finally, we can also generate a Changelog entry instead of a commit message. We just need to make the following tweak to the prompt: “Generate a Changelog entry given the following code changes.”13. Other use cases
After reviewing all those use cases, I encourage you to consider other documentation-related tasks where AI models could provide assistance!14. Let's practice!
In the meantime, let's practice!Create Your Free Account
or
By continuing, you accept our Terms of Use, our Privacy Policy and that your data is stored in the USA.