Code Comments

A good code comment explains WHY, not WHAT — the code shows what. Good comments describe intent, workarounds, warnings, or non-obvious constraints: "// Using polling instead of WebSockets due to corporate proxy restrictions", "// Don't change this order — breaks the legacy API contract". Avoid commenting obvious code: "// increment counter by 1" adds no value and creates maintenance burden.

Comment types: Intent comments (explain why), TODO/FIXME markers (pending work — always include a ticket reference), Warning comments ("// side effect: clears the cache"), API documentation (JSDoc, docstrings — describe parameters, return values, exceptions), Licence headers (legal requirements at file top), Section delimiters (organise long files). Each serves a specific purpose in code maintenance.

Best practice format: "TODO(username): description [ticket-ref]" — e.g., "// TODO(alex): remove after migration to v2 API [JIRA-1234]". FIXME indicates a known bug: "// FIXME: race condition under high load — see JIRA-456". HACK or XXX marks questionable code requiring review. Always include a ticket reference — orphaned TODOs without context become technical debt that nobody addresses.

JSDoc format: `@param {type} name - description`, `@returns {type} - what the function returns`, `@throws {ErrorType} - when this exception is raised`, `@example - code example`, `@deprecated - Use [alternative] instead since v[version]`. Use imperative mood in the description: "Returns the user by ID" (not "This function will return..."). Keep descriptions concise — one line per parameter is usually enough.

Avoid: (1) Obvious restatements — "// creates a new user" above a `createUser()` function; (2) Dated references — "// added on 2024-01-15" (use git blame); (3) Commented-out code without explanation — delete it or explain why it's kept; (4) First-person pronouns without context — "// I changed this to..." (use commit messages); (5) Negative comments about colleagues — "// this is terrible code by John". Professional, constructive, and impersonal.

Inline comments appear on the same line as code: `x = x * 2; // double the value for display purposes`. Block comments (docstrings) appear above a function or class and document its interface. Inline comments should be rare — if a line needs a comment to be understood, consider renaming the variable or extracting a function instead. Block/docstring comments are systematic documentation expected for public APIs.

Complex algorithm comments should: (1) Reference the algorithm name and source ("// Knuth-Morris-Pratt string matching — see CLRS 3rd ed., p.1002"); (2) Explain time/space complexity ("// O(n log n) — acceptable for n < 10,000 records"); (3) Describe preconditions ("// Assumes input array is sorted in ascending order"); (4) Note why a simpler approach doesn't work ("// Can't use a hash map here because order matters"). These save hours for future maintainers.

Python uses triple-quoted docstrings: `"""Summary line.\n\nArgs:\n name (str): Description\n\nReturns:\n dict: Description\n"""`. Common formats: Google style, NumPy style, Sphinx reST. JavaScript uses `/** ... */` JSDoc: `@param {string} name - Description`. Both serve the same purpose — documenting the API contract. The key difference is placement: Python docstrings are inside the function body; JSDoc goes above the function.

Update comments when: (1) the implementation changes and the comment describes the old behaviour; (2) a workaround is resolved and the warning comment is no longer valid; (3) a TODO is completed (remove the comment); (4) referenced ticket numbers change. Outdated comments are worse than no comments — they actively mislead developers. Code review checkers like "has the comment been updated to match the code?" should be part of your review checklist.

Security comments: "// SECURITY: never log this value — contains credentials", "// IMPORTANT: validate input before this point — SQL injection risk if called directly", "// CSRF token check — do not remove this validation", "// Intentional constant-time comparison — prevents timing attacks". Security warnings should be prominent and specific about the risk. Use uppercase labels (SECURITY, WARNING, IMPORTANT) to make them scannable.