diff --git a/.cursor/rules/comments.mdc b/.cursor/rules/comments.mdc new file mode 100644 index 00000000..e732e859 --- /dev/null +++ b/.cursor/rules/comments.mdc @@ -0,0 +1,35 @@ +--- +alwaysApply: true +--- + +# Comment Guidelines + +## Good Comments (Human-style) +- Explain WHY, not WHAT +- Document non-obvious behavior or edge cases +- Warn about performance implications or side effects +- Explain business logic that isn't clear from code + +Examples: +```javascript +// transfer, not copy; sender buffer detaches +// satisfies: check shape; keep literals +// keep multibyte across chunks +// timingSafeEqual throws on length mismatch +``` + +## Bad Comments (AI-style) +- Don't explain what the code literally does +- Don't add changelog-style comments in code +- Don't comment every line or obvious operations + +Avoid: +```javascript +// Prevent duplicate initialization +// Check if project is already loaded +// Mark as initializing to prevent race conditions +// (changed from blah to blah) +``` + +## Rule +Only add comments when there's genuinely non-obvious behavior, performance considerations, or business logic that needs context. Code should be self-documenting through naming and structure. \ No newline at end of file