1. Forum
  2. DOVE-Net
  3. Synchronet Programming

  • src/CLAUDE.md

    From Rob Swindell (on Debian Linux)@VERT 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>

    ---
    þ Synchronet þ Vertrauen þ Home of Synchronet þ [vert/cvs/bbs].synchro.net
  • From Rob Swindell (on Debian Linux)@VERT to Git commit to main/sbbs/master on Fri Jul 24 23:28:15 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>

    ---
    þ Synchronet þ Vertrauen þ Home of Synchronet þ [vert/cvs/bbs].synchro.net
  • From Rob Swindell (on Debian Linux)@VERT to Git commit to main/sbbs/master on Sun Jul 26 15:23:20 2026
    https://gitlab.synchro.net/main/sbbs/-/commit/a4d3c7246f653789b510cf70
    Modified Files:
    src/CLAUDE.md
    Log Message:
    src: date a commit reference, in a message or a comment

    A bare SHA says nothing about when. A reader cannot tell whether the commit being cited comes before or after the code in front of them, nor line it up against a release or a bug report -- and that ordering is usually the whole reason the commit was worth naming. The date also outlives the SHA, which
    stops resolving in a mirror, a tarball, or a rewritten branch.

    Says to use the commit's own author date and to read it from the repo
    rather than guess, since a wrong date is worse than none: it is
    confidently checkable, and it will be checked.

    Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

    ---
    þ Synchronet þ Vertrauen þ Home of Synchronet þ [vert/cvs/bbs].synchro.net