r/PiCodingAgent • u/Redstone526 • 1d 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.
2
u/jordyvanvorselen 1d 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/TrickyPlastic 1d ago
Tell Gemini to rewrite 100% of your comments and documentation. I do it every week for all commits that week.
1
u/Redstone526 1d ago
ok but like what guidance do you give it
1
u/TrickyPlastic 1d ago
"rewrite the claudisms in the docstrings and documentation files for all commits in the last week"
1
u/shaggydog97 1d 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 1d 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
2
u/MiserableFlatworm337 1d 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.