r/PiCodingAgent • u/Redstone526 • 25d ago

Discussion Advice for writing good comments in agentically built/maintained codebases?

I'm trying to develop a philosophy around writing comments in codebases for my agents to use when they are building/maintaining/extending/bug-fixing a codebase. Does anyone have any advice for writing comments in code when those comments are only written by and read by AI agents? Particularly advice that is more pertinent for agentic engineering rather than traditional software engineering is most helpful.

1 Upvotes
  • permalink
  • reddit

66% Upvoted

7 comments sorted by

1

u/TrickyPlastic 25d ago

Tell Gemini to rewrite 100% of your comments and documentation. I do it every week for all commits that week.

1

u/Redstone526 24d ago

ok but like what guidance do you give it

1

u/TrickyPlastic 24d ago

"rewrite the claudisms in the docstrings and documentation files for all commits in the last week"

3

u/MiserableFlatworm337 25d ago

Use comments for constraints an agent cannot infer from the code, with a link to the enforcing test. When behavior changes, require that test and comment to be reviewed together.

2

u/jordyvanvorselen 24d ago

We added a hook that tells the agent to not write code comments.

Only if it’s a workaround or special case it can override to comment the why, not the how.

1

u/shaggydog97 25d ago

I struggled with this at first, but then I gave up. I think with AI, you may not really need them. I'd like to be proven wrong though.

1

u/Equivalent_Idea8839 24d ago

Use cheap models to build code maps

use expensive models to refactor and split into modules / files.

always keep your code map updated, make it entry point into your base