Lesson 14 / 25

Docs, Comments and Commit Messages

Use assistants to draft documentation and commit messages, then correct them with facts.

Draft fast, edit for truth

Assistants are good at turning a diff into a commit message, a function into a docstring, or notes into a README section. The risk is text that sounds right but describes behaviour the code does not have. Read each sentence against the code. Prefer comments that explain why over comments that repeat what the line obviously does.

A prompt for a commit message

Give it the diff and the style you use. Conventional Commits is a common format.

git diff --staged | pbcopy     # or xclip / clip on your OS
# Prompt: "Write a Conventional Commits message for this diff.
#          Subject under 72 chars, then a short body explaining WHY."

Document the why in the code

Business reasons and past incidents are exactly what an assistant cannot know. Write short comments for non-obvious decisions yourself so future readers, and future assistants, have the context.

Quick check: What is the main risk of AI-written documentation?

  • It deletes comments
  • It is always too short
  • It cannot use Markdown
  • It may describe behaviour the code does not actually have
Answer

It may describe behaviour the code does not actually have — Fluent text can be inaccurate, so verify each claim against the code.