From 248f2694bc817e3a973801547b48a00a288289e4 Mon Sep 17 00:00:00 2001 From: Zef Hemel Date: Mon, 3 Aug 2026 16:02:57 +0200 Subject: [PATCH] Code style updates --- STYLE.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/STYLE.md b/STYLE.md index 1f044fd0..c45344e0 100644 --- a/STYLE.md +++ b/STYLE.md @@ -94,9 +94,13 @@ export function listPages(unfiltered?: boolean): Promise { } ``` -Inline comments: -* In case of doubt: add comments around the _why_ of the code (not what) -* Add TODO comments for known issues +Inline comments: write one only when it definitely earns its place: a non-obvious _why_, a constraint not visible in the code, a workaround for an external bug, or a subtle ordering/safety requirement. + +Don't: +* restate what the code already says, or narrate a function's steps +* write a doc comment that only repeats the signature +* explain what a better name or an extracted function would make obvious + ```typescript // Note: these events are dispatched asynchronously (not waiting for results)