Code traps

Some code in FreeITSM looks as if it could be simpler, and isn't. Usually a real install once proved why: a bug that lost data, leaked across companies or broke silently. Those rules are marked in the code itself, in one shape, so they're hard to miss and easy to find.

// TRAP: never trust a serviceUrl the token does not vouch for.
//   Replies are POSTed to it WITH THE BOT'S ACCESS TOKEN, so an activity that
//   could name its own serviceUrl could collect that token.

• TRAP: then the rule, in one sentence, as an instruction.
• Then why, in a line or two — what goes wrong if you ignore it.
• The full story, if there is one, lives in the developer guide the file's header points to, not in the comment.

Finding them

git grep -n "TRAP:"                         # every trap in the codebase
git grep -n "TRAP:" -- includes/messaging   # the ones in one area

Before changing a file, read its TRAP: lines. They are written for people and for AI coding assistants alike: a trap is the thing a confident edit is most likely to undo.

Writing one

Add a TRAP: when you fix something that a sensible-looking change would bring back — and a test that fails if it does. Keep it short: a trap that runs to a paragraph is a design note, and belongs in the wiki.

Older code marks the same kind of rule with 🔴 or ⚠️ and a longer explanation. Those are just as binding; new ones use TRAP: so they can be listed.

---

See also: Teams and Mattermost — Developer Guide (where the convention started) · Telegram — Developer Guide: the traps