Add Docstrings and Why-Focused Comments to Your Pasted Code

Returns your code with standard-style docstrings covering parameters, return values and raised errors, plus comments that explain intent rather than restate the code.

You getThe full documented code in one code block and changes

Prompt

Prompt
Act as a senior software engineer who reviews code for readability.

I will paste code right after this message. Add docstrings and comments without changing what the code does.

Rules:
1. Detect the language and use its standard docstring style: Google style for Python, JSDoc for JavaScript/TypeScript, Javadoc for Java, XML doc comments for C#, GoDoc for Go. If the file already follows a style, match it.
2. Every public function, method and class gets a docstring with a one-line summary in the imperative mood. Follow it with each parameter's type and meaning, the return value, and every error the code raises or lets pass through.
3. Inline comments explain why: intent, edge cases, workarounds, non-obvious limits. Never write a comment that restates what a line plainly does.
4. Do not rename, reorder or refactor anything. If you spot a likely bug, flag it in a comment starting with NOTE: and leave the code as is.
5. If the purpose of a block is unclear, add a comment asking what it is for. Do not guess.

Output format:
1. The full documented code in one code block.
2. Changes: one bullet per function or class describing what you added.
3. Open questions: anything you could not infer from the code.

End with one line listing any assumptions you made about types or intended behavior.

Example output

At a glanceWhat was added to fetch_with_retryDocstring and comment changes in the example output
Parameters documented
3
url, retries, backoff
Raised errors documented
3
HTTPError, ConnectionError, ValueError
Why-focused comments added
2 + 1 NOTE
4xx skip, backoff delay, retries=0 note
Open questions raised
3
retries=0, fixed timeout, Timeout not retried

Example for: a Python helper that calls an internal inventory API with retries.

import time

import requests


def fetch_with_retry(url, retries=3, backoff=0.5):
    """Fetch a URL and return its JSON body, retrying on server and network errors.

    Args:
        url (str): Absolute URL of the endpoint to call.
        retries (int): Maximum number of attempts, including the first. Defaults to 3.
        backoff (float): Base delay in seconds. It doubles after each failed attempt.
            Defaults to 0.5.

    Returns:
        dict: The decoded JSON response body.

    Raises:
        requests.HTTPError: On any 4xx response, or on a 5xx response during the final attempt.
        requests.ConnectionError: If the host is unreachable on the final attempt.
        ValueError: If the response body is not valid JSON.
    """
    # NOTE: if retries is 0 the loop never runs and the function returns None silently.
    for attempt in range(retries):
        try:
            resp = requests.get(url, timeout=10)
            resp.raise_for_status()
            return resp.json()
        except (requests.HTTPError, requests.ConnectionError) as err:
            # A 4xx means the request itself is wrong, so a retry would fail the same way.
            if isinstance(err, requests.HTTPError) and err.response.status_code < 500:
                raise
            if attempt == retries - 1:
                raise
            # Exponential backoff gives an overloaded server time to recover.
            time.sleep(backoff * 2 ** attempt)
Changes
  • fetch_with_retry: added a Google-style docstring covering all three parameters, the return type and three raised errors.
  • fetch_with_retry: added one comment explaining why 4xx errors skip the retry.
  • fetch_with_retry: added one comment explaining the backoff delay.
  • fetch_with_retry: added a NOTE about the silent None return when retries is 0.
  • Left the timeout=10 line without a comment, because its meaning is clear from the argument name.
Open questions
  • Should retries=0 be rejected with a ValueError, or is the None return expected by callers?
  • Is the fixed 10-second timeout a deliberate service limit? If so, it may be worth a named constant or a comment.
  • Timeouts (requests.Timeout) are not retried. Is that intentional?

Assumptions: the API always returns a JSON object (not a list), and requests 2.27 or later, where JSON decode errors subclass ValueError.

Written by AI from this prompt. Your results will vary.

Tips and common edits

Why this works

  • Naming the docstring style per language gives output that matches linters and IDE tooltips instead of a generic format.
  • Requiring raised errors in every docstring makes the model trace failure paths, which often surfaces hidden bugs.
  • Banning what-comments and refactors keeps the diff small and reviewable, with bugs flagged rather than silently changed.

Use before a code review or when handing code to a teammate. Paste one file or a few related functions into ChatGPT, Claude or Gemini. For large files, send one module at a time.

Common edits

  • Switch Python to NumPy or reST docstring style to match your project's Sphinx setup.
  • Allow light refactoring, such as renaming unclear variables, and ask for a separate list of those changes.

Prompt details

By
Prompts-GPT editors
Published

Did this prompt work?

Keep exploring

More in Coding