1. Forum
  2. FidoNet
  3. SYNC PROGRAMMING

  • src/CLAUDE.md

    From Rob Swindell (on Debian Linux)@1:103/705 to Git commit to main/sbbs/master on Thu Jul 23 23:03:46 2026
    https://gitlab.synchro.net/main/sbbs/-/commit/f6ad99ad9215937858314696
    Added Files:
    src/CLAUDE.md
    Log Message:
    src: add a CLAUDE.md directive on C/C++ comment discipline

    Comments in the C/C++ sources should explain the non-obvious, not narrate
    the change or its history -- git log/blame/annotate and the commit message
    are the archaeology tools, and rationale belongs in the commit message where
    it stays tied to the exact diff. Recent output_thread() edits drifted into block comments that were really commit-message prose in the wrong place;
    this scopes a directive at src/ (auto-loading for sbbs3, syncterm, ssh,
    doors, ...) to head that off.

    Permitted comments: genuinely surprising/edge-case code (kept short), a
    direct GitLab issue pointer (with the problem's details in the issue, which auto-links to the fix commit), and terse tool/analyzer directives that must
    sit at the code site with a one-line justification.

    Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
    --- SBBSecho 3.37-Linux
    * Origin: Vertrauen - [vert/cvs/bbs].synchro.net (1:103/705)
  • From Rob Swindell (on Debian Linux)@1:103/705 to Git commit to main/sbbs/master on Fri Jul 24 23:28:14 2026
    https://gitlab.synchro.net/main/sbbs/-/commit/f65caf0f81181572c918f79f
    Modified Files:
    src/CLAUDE.md
    Log Message:
    CLAUDE.md: commit messages are written for a future human

    The commit-message guidance in the tree covers style (78-column wrap) and
    what to put in a message rather than in a comment, but nothing says who the message is for. Add that: a commit message is read cold, months later, by someone who was not present when the change was made.

    The rule that motivated this is the ban on ephemeral local state. Working tree, index, scratch worktrees, a file reverted part-way through, what HEAD happened to be at the time -- none of it exists for the reader and none of it survives the commit, so a sentence like "Both files are therefore back to
    HEAD" reads as a stray chat reply. Session narration goes with it: no list
    of approaches tried and abandoned, no "as discussed above", no addressing the reader as the person who asked for the change.

    Closes with a test to apply before committing -- read the message as though
    you had never seen the work happen, and cut any sentence that only makes
    sense to someone who did.

    Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
    --- SBBSecho 3.37-Linux
    * Origin: Vertrauen - [vert/cvs/bbs].synchro.net (1:103/705)