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.