← Back to library

▶ quest log

Why Long AI-Written Comments Are Worth Keeping

Engineering Best PracticesIntermediateAdvanced@thewholedaisysaved AUG 03

◇ Could this help me?

Yes, with the condition treated as mandatory rather than optional. The token economics are real, and a comment that records why a line exists is genuinely valuable context for both people and models, so this is worth adopting for comments that explain intent and constraints. The risk is the part the video mentions in passing: a stale comment is worse than no comment because it confidently misleads the next reader, human or model, and almost no codebase actually has a process validating comment accuracy. Adopt the practice only alongside a real review habit that updates or deletes the comment whenever the code beneath it changes. This is a general practice.

✦ Walkthrough+10 xp / step
0 / 4 steps · adopt for +40
$ suggested_prompt+40xp

Review the explanatory comments in the files I point you at. For each long comment block, tell me whether it still accurately describes the code beneath it, whether it records intent and constraints that are not obvious from the code itself, or whether it merely restates what the code plainly says. Recommend keep, update, or delete for each one, and rewrite the ones you mark update.

More from Engineering Best Practices

Enter world →