Code Comments

What Code Comments Are For

Code comments are a communication layer for humans, not for the runtime. They help explain intent, document assumptions, and clarify why a block of code exists, especially when the implementation is non-obvious or technically dense. Good comments reduce cognitive load for maintainers; poor comments add noise or create false confidence.

The main value of comments is that they preserve context that the code itself may not express cleanly. That includes business intent, security rationale, edge cases, and design trade-offs. Used well, they make future change safer because a maintainer can see not just what the code does, but why it was written that way.

How Comments Help Maintenance and Review

Comments are most useful during review, debugging, refactoring, and handover. They can highlight invariants, explain unusual control flow, or warn that a particular dependency, order of operations, or edge case matters. In practice, this is where comments function as a lightweight form of operational memory for the codebase.

They are also useful for reviewers who need to judge whether a change alters intended behaviour. A clear comment can surface the design assumption that a patch must preserve. That said, the comment should explain the reasoning, not restate the code line by line, because repetition becomes stale quickly and is easy to ignore.

When Comments Become a Source of Error

Comments can mislead when they drift away from the code. A stale comment may describe a behaviour that no longer exists, or it may omit a later change that now makes the statement untrue. In security-sensitive code, that gap can be especially harmful because reviewers may trust the comment and miss a real control failure or an outdated assumption.

Inline commentary can also become a maintenance burden when teams use it to justify poor naming, unclear structure, or complex logic that should instead be simplified. The best comments support readable code; they do not compensate for code that is hard to understand on its own.

Comment Quality and Safe Usage

Effective comments are specific, durable, and limited to information that is not obvious from the code itself. They are strongest when they describe intent, constraints, or non-obvious consequences. Comments should usually be updated at the same time as the code they describe, because their accuracy depends on staying aligned with implementation changes.

A practical rule is to comment the reason, not the mechanics. If the code already says what happens, the comment should explain why that approach was chosen, what assumption must remain true, or what a future maintainer must not break.

Risk and Threat Considerations

Outdated comments can create security and reliability risk by preserving a false picture of how code behaves. In review, that can hide weak validation, bypassed checks, or assumptions about ordering, authentication, or trust boundaries that are no longer true.

Failure mechanism: A misleading comment convinces a maintainer or reviewer that a control exists, still applies, or is handled elsewhere, so the real code path is not scrutinised closely enough.

Impact: The result can be missed defects, flawed remediation, insecure refactors, and weaker assurance that security-relevant logic still matches its documented intent.

Practitioner Guidance

Common misunderstanding: Comments are often treated as a substitute for clear code, but they are only reliable when they stay close to the implementation and explain something the code cannot easily express.

Why practitioners should care: Comment quality directly affects maintainability, review effectiveness, and confidence in security-sensitive changes. Keep comments concise, current, and tied to intent or constraints, and remove them when they no longer add value.

Related resources from NHI Mgmt Group

• What do security teams get wrong about comments in generated code?
• How can developers prevent suspicious comments in code?
• What is the difference between secret leakage in code and secret leakage in comments?
• Why is hardcoding credentials into source code so dangerous?