OpenPuck/AGENTS.md

AGENTS.md

Code style

• Linux kernel style, enforced by .clang-format (8-wide tabs, 80 columns). Pinned to clang-format 18 — other versions reformat differently and CI will reject them.

Comments

Comment to explain why, not what — the code already says what it does. This codebase reverse-engineers an RF/HID protocol, so the comments worth writing are the ones that capture knowledge the code can't show on its own.

Write a comment only when it carries genuine nuance:

• the meaning of a magic value or protocol constant,
• a hardware / host-OS quirk or gotcha,
• a non-obvious constraint or consequence ("lower than 96 truncates the battery report → CRC fail"),
• why a non-obvious approach was chosen over the obvious one.

Delete a comment if it:

• restates the code (i++; // increment i),
• narrates history or changelog ("was 64, bumped to 96"),
• editorializes ("THE fix", "the magic part"),
• leaves debug / A-B-test breadcrumbs.

Keep the constraint, drop the story. Prefer no comment to an obvious one; when tempted to annotate, first see if clearer code makes the comment unnecessary.

No long trailing comments. clang-format can't relocate a trailing // comment, so a long one either splits the statement or runs past 80 columns. Put it on its own line(s) above the statement, with a blank line before it:

// 0xE7 selects the protocol-version handshake; 0xE3 is the steady-state poll
uint8_t g_connType = 0xE7;

not

uint8_t g_connType = 0xE7; // 0xE7 selects the protocol-version handshake ...

Short trailing comments that fit within 80 columns are fine. The lint (make lint) enforces only the column rule; the rest is on you and review.

Before pushing

make format   # auto-format (kernel style)
make check    # what CI gates on: format-check + trailing-comment lint

CI rejects a PR immediately if either fails. The lint lives in tools/check-trailing-comments.py.

Build / compile-check (no hardware needed)

arduino-cli compile -b adafruit:nrf52:feather52840 \
  --build-property "build.extra_flags=-DNRF52840_XXAA {build.flags.usb} -DCFG_TUD_HID=4" \
  OpenPuck

OpenPuck/git_version.h is generated by gen_version.sh and gitignored — never commit it.