Claude code, a young power tool with some practices that can easily be improved on.
Best practices for documenting: Legacy code + AI changes
// A simple, obvious, "What was done where?"
I have, for decades, STAMPED my code changes
with a hot key that appended
"// JT 25.07.29 16" at end of a line.
// Who, when, where, what, sometimes even a "why"
This translates to an AI best practice of:
Tell Claude to stamp its changes and note this in its .md file.
// AI [YY.MM.DD] [DAYS_CHANGE_NUMBER (functionName)
Claude code conversations go by very quickly. That above (functionName) is very important for high level understanding of the changes as they fly by and finding those changes later in the code. It contextualizes.
For you, this convention translates to an coder best practice of a hot key for stamping your changes:
// YOUR_INITIALS [YY.MM.DD] [CHANGE_NUMBER]
Decades of stamping makes me an expert at
readable code evolution in general and
more importantly AI assisted code evolution specifically.
Claude code is a young power tool for making changes.
The question becomes how to best guide Claude in making the changes
and then making sense of those changes.
When in doubt, state the obvious:
Claude code's default conversational conventions lack an important detail,
the CONTEXT of the changes it is making.
Claude shows the file name it is making the change to. But more detail is needed.
As illustrated above,
What function is the change being made to? Is very important.
Legacy code + AI changes,
should be maximally human-readable.
// Who made the changes? , AI/initials
// When were the changes made?, 25.07.29
// Where the change was made? - ostensive
// What change was made? - ostensive
What was done where? - is my takeaway from hrs of coding.
Stamping, best practice (BP) byproduct:
You can search for all changes by date.
I search for today's changes frequently, I suspect you will too.
Stamping helps answer the coder proverbial question:
Who broken what, when, where?
Claude is very useful and very error prone.
Stamping is a convention that helps track changes and deal those errors. Even Claude admits this ;-)
Warning: Claude can get frustrated, "this is not working" and just discard many hrs of progress by over writing the whole file(s). (This after being told in the .md to ALWAYS make a backup copy) Ergo, snapshot backup frequently.
Intelligence:
Knowing, you dont know what you dont know.
Jean Tantra // JT 25.07.29
Apple Mac developer since 1986
www.metatheory.com
Stamping@metatheory.com
Top comments (0)