When code behavior, limitations, or implementation decisions are not immediately obvious from reading the code itself, add explanatory comments to clarify the reasoning and context. This is especially important for:
Example from the codebase:
// @ts-expect-error TS2416 Types insist value is a Socket, but it's actually unknown
set connection(value: unknown) {
// Note: #socket is not actually used for anything other than making
// the property available for compatibility
this.#socket = value;
}
/* eslint-disable @typescript-eslint/no-deprecated */
// Disabling deprecated warnings for this.finished and other attributes
// which are deprecated in types/node package but required for compatibility
This practice prevents confusion for future maintainers and helps reviewers understand the context behind implementation choices.
Enter the URL of a public GitHub repository