Code Quality Review

JSDoc:

• All public and private APIs must have JSDoc comments.
• New hooks and configuration options must include a @since tag.
• Use Markdown formatting, not HTML tags. Line breaks use empty lines, never <br>.
• Use [[MY_LINK]] syntax for links, not {@link MY_LINK}. End every sentence with a full stop.

Private fields:

• Use the # prefix for private class fields and methods. Do not use @private JSDoc tag unless # is avoided for documented performance reasons.

Naming:

• Full names required: row and columns, not cols. Use Handsontable in text, never HOT.
• Functions: camelCase. Classes: PascalCase. Constants: UPPER_SNAKE_CASE.
• Public API names must be generic, self-explanatory, and collision-free.

Cognitive complexity:

• Each function must stay at 15 or below on the Sonar cognitive-complexity metric. Extract helpers or add early-return guards when exceeded.

Optional chaining (?.):

• Use only when a value is genuinely optional by design. Do not use as a blanket safety net for values guaranteed by the data contract.

Silent catch blocks:

• Every empty or swallowed catch must include a comment explaining why the error is ignored.

Browser compatibility:

• Verify that all JS and CSS APIs are supported across browsers listed in browser-targets.js at the repo root.

Bundle size:

• Prefer grammar that produces smaller compressed output (e.g., === over verbose helpers, short-circuit evaluation over full if blocks).

DRY:

• No duplicated logic. Reuse existing helpers and mixins from src/helpers/. Extract shared code into utility functions.

Core language boundary:

• No TypeScript files in handsontable/src/. Core is JavaScript only. Type definitions go in handsontable/types/ as .d.ts files.

Documentation and AGENTS.md updates:

• If the change introduces new conventions, constraints, or gotchas, require an AGENTS.md update.
• User-facing behavior or UX changes require matching docs updates in docs/content/.

Public API naming:

• New option, hook, and method names must be generic, self-explanatory, and free of internal jargon.
• Check for collisions with existing API names (options, hooks, methods, plugin keys, CSS classes) before approving.
• Public API names carry long-term maintenance weight -- once released, they must be maintained indefinitely.