.continue/checks/stale-comments.md
In a fast-moving TypeScript monorepo with many contributors, comments frequently fall out of sync with the code they describe. A misleading comment is worse than no comment — it actively misdirects developers and causes bugs. This check catches comments that contradict, no longer match, or misrepresent adjacent code.
Look for inline comments (//) and block comments (/* */) where the description no longer matches what the code actually does.
BAD — comment says "retry" but code doesn't retry:
// Retry the request on failure
const result = await fetch(url);
BAD — comment describes old parameter list:
// Takes a model name and returns the provider
function getProvider(config: ModelConfig, context: ContextManager) {
GOOD — comment matches behavior:
// Resolve provider from full model configuration and context
function getProvider(config: ModelConfig, context: ContextManager) {
Flag TODO, FIXME, and HACK comments where the described work appears to already be done in the surrounding code.
BAD — TODO says to add validation, but validation exists below:
// TODO: add input validation
if (!input || typeof input !== "string") {
throw new Error("Invalid input");
}
Flag blocks of commented-out code that have an annotation suggesting they're still needed, when the functionality has been replaced or removed.
BAD:
// Keep this for fallback support
// const oldProvider = new LegacyProvider(config);
// oldProvider.initialize();
const provider = new ModernProvider(config);
Check that @param, @returns, and @throws tags in JSDoc comments match the actual function signature — correct parameter names, types, and return type.
BAD — documents a param that doesn't exist:
/**
* @param modelName - The model to use
* @returns The completion text
*/
async function complete(config: AutocompleteConfig): Promise<Result> {
core/ — shared logic across all extensionsextensions/vscode/src/ — VS Code extension sourceextensions/cli/src/ — CLI extension sourcegui/src/ — React GUI componentspackages/ — shared npm packagesnode_modules