# How do you write code comments that guide an AI coding assistant?

Date: 2022-11-05 · Author: Robert Scales · https://guidetoartificialintelligence.com/en/learn/write-code-comments-that-guide-ai-coding/

**Answer:** Write the comment or docstring as a small specification before the code: what goes in, what comes out, the edge cases, and one or two examples. An assistant like GitHub Copilot predicts code from the text above the cursor, so a precise description narrows its guesses and makes the result easier to check.

GitHub Copilot, the AI pair programmer that runs inside editors such as Visual Studio Code, suggests code as you type. It reads what is already in your file, including comments, and predicts what should come next. GitHub's own getting-started guide shows the simplest version: type a plain-English comment, and Copilot proposes code that does what the comment describes.

That makes your comments a kind of prompt. A vague comment gets a plausible guess. A precise one gets something much closer to what you need. One practical way to work is **docstring-driven development**: before writing a function, you write its docstring, the description that sits at the top of a function in Python, as if you were explaining the job to a careful colleague. Then you let the assistant draft the body and check it against what you wrote.

## Why the comment matters so much

Copilot is powered by a version of OpenAI's Codex, a GPT model trained on public code from GitHub. The Codex research paper tested it in a way that maps neatly onto this habit. Its benchmark, called HumanEval, gives the model a function signature and a docstring, then runs unit tests on the code it writes. In other words, the researchers measured how well Codex turns a docstring into working code.

The paper also found a clear weakness. As a docstring describes more chained steps, Codex's success rate falls sharply, by a factor of two or three for each extra step. The lesson for everyday use: describe one job per function, and break long processes into several small functions, each with its own short docstring.

## A worked example: before and after

Suppose you need to clean up phone numbers entered in a sign-up form.

**Before: a vague comment.**

```prompt
# clean phone number
def clean_phone(s):
```

Copilot can only guess. It might strip spaces, or remove every non-digit, or add a country code. Any of those could be right, and you have no way to tell from the comment which one you meant.

**After: a docstring written as a specification.**

```prompt
def clean_phone(raw: str) -> str:
    """Normalize a North American phone number to the form 555-123-4567.

    Accepts digits with any mix of spaces, dots, dashes and parentheses.
    A leading country code of 1 or +1 is allowed and removed.
    Raises ValueError if the result is not exactly 10 digits.

    Examples:
        clean_phone("(613) 555-0199")   -> "613-555-0199"
        clean_phone("+1 613.555.0199")  -> "613-555-0199"
        clean_phone("555-0199")         -> ValueError
    """
```

Now the assistant knows the input, the output format, the optional prefix, the error case and three concrete examples. The type hints (`str` in, `str` out) add more signal. The suggestion you get is far more likely to match, and the examples double as a checklist: run each one and see whether the code behaves as promised.

Here is what changed between the two versions:

| Element | Vague comment | Specification docstring |
|---|---|---|
| Output format | Missing | 555-123-4567 |
| Accepted input | Missing | Spaces, dots, dashes, parentheses |
| Edge case | Missing | Leading 1 or +1 removed |
| Failure behavior | Missing | ValueError if not 10 digits |
| Examples | None | Three, including one failure |

A few more habits help. Put the comment directly above where the code should start, so it is the last thing the model reads. Use the same words your code uses: if a variable is called `invoice_total`, don't call it "the amount" in the comment. And if the first suggestion misses, read the alternatives; in VS Code, Ctrl+Enter opens a panel with several options.

> **Try it:** Choose a small function you need this week. Write its docstring first, with input, output, one edge case, one failure case and two examples. Let Copilot suggest a body, then turn your examples into tests and run them. If a test fails, ask whether the code is wrong or the docstring was unclear, and fix whichever it is.

## What comments can't do

A good docstring raises the odds of a useful suggestion, but it does not guarantee correct code. GitHub states that Copilot does not run or test what it writes, that its suggestions may not work, and that it can repeat insecure patterns found in public code. The specification is valuable precisely because it gives you something to check the suggestion against.

## How do you keep its suggestions consistent with your project?

Copilot copies the patterns it can see. GitHub has described it as drawing its context mainly from the file you are editing, and in long files only the preceding few hundred lines are used. So the most reliable way to keep suggestions in your project's style is to make that style visible near where you are working.

In practice, that means a few things. Keep your imports at the top of the file, so Copilot reaches for the libraries you already use instead of others. Write one function by hand in your preferred style, with your naming, error handling and logging, and place new functions after it; the assistant tends to follow the example. Use type hints and consistent names, because they repeat the same signals on every line. If your project has helper functions for dates, money or database access, mention them by name in the docstring ("use `parse_iso_date` from utils") so the suggestion calls your helper rather than writing a new one.

Finally, keep your normal safeguards in place. A linter and formatter, tools that check and tidy code automatically, will catch style drift. Your existing tests will catch behavior drift. Reviewing every suggestion as if it came from a new teammate keeps the code yours.

## Sources

- Getting started with GitHub Copilot in Visual Studio Code: https://web.archive.org/web/20221006173042/https://docs.github.com/en/copilot/getting-started-with-github-copilot/getting-started-with-github-copilot-in-visual-studio-code
- Evaluating Large Language Models Trained on Code: https://arxiv.org/abs/2107.03374
- GitHub Copilot: Your AI pair programmer (product page and FAQ, June 2021): https://copilot.github.com/