L11 Commenting Security

title: "Commenting Security — Documenting Security-Critical Code and Avoiding Information Leaks" weight: 11 description: "Learn how to comment security-critical code and avoid information leaks in code comments. Master security-focused commenting practices that document cryptographic code, input validation, and access control without exposing vulnerabilities." date: 2026-06-28 lastmod: 2026-06-28 tags: [technical-writing, code-comments]

Security comments document security-critical code and design decisions. They help reviewers verify security properties and future maintainers avoid introducing vulnerabilities. However, security comments can also leak information that helps attackers.

In this lesson, you will learn how to document security-critical code safely.

## What You'll Learn

You will document security-critical code, avoid information leaks in comments, and use comments to support security reviews.

## Why It Matters

Security comments help maintainers understand why security measures exist and not accidentally remove them. But comments that reveal implementation details can aid attackers.

## Real-World Use

DodaTech security team reviews all comments in security-critical modules. Comments must explain why security measures exist without revealing exploitable details.

```mermaid
flowchart LR
  A[Security Code] --> B[Comment Purpose]
  B --> C[Why Security Exists]
  B --> D[What It Protects]
  B --> E[NOT How to Bypass]
  C --> F[Safe Documentation]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

What to Document in Security Code

Document why security measures exist. What threat do they protect against? Why is this approach appropriate?

Document security assumptions. What must be true for the security measure to be effective?

Document failure modes. What happens if the security measure fails? How is failure detected?

Document security review requirements. If the code is reviewed for security, mention it in the comment.

# Security: Input validation for compression paths
# This prevents directory traversal attacks where an attacker provides
# a path like "../../etc/passwd" to access files outside the allowed
# directory. The validate_path function checks that the resolved path
# is within the allowed base directory.

def validate_path(path: str, allowed_base: str) -> bool:
    """Validate that a path is within the allowed base directory."""
    import os
    # Resolve the path to prevent .. traversal
    resolved = os.path.realpath(path)
    base = os.path.realpath(allowed_base)
    # The resolved path must start with the base path
    return resolved.startswith(base)

What NOT to Document

Do not document how to bypass security measures. Comments like This check can be bypassed by... help attackers.

Do not document specific vulnerabilities in comments. If a vulnerability exists, create a private ticket, not a public comment.

Do not document security weaknesses that cannot be fixed immediately. If you must note a limitation, reference a security ticket.

# DANGEROUS: Do NOT write comments like this
# BUG: The path validation does not handle symlinks inside the
# allowed directory. You can bypass it by creating a symlink.

# SAFE: Use a ticket reference instead
# SECURITY-456: Path validation edge case with symlinks
# Tracked in security review board. Do not modify without approval.

Common Mistakes

1. Documenting Bypass Methods

Comments that tell the reader how to circumvent security measures.

2. Exposing Secrets

Hardcoded passwords, API keys, or tokens in comments. Never put secrets in source code or comments.

3. No Security Context

Security code without explanation of what it protects. Future developers may remove it.

4. False Sense of Security

Comments claiming security that does not exist. Document actual security properties, not aspirational ones.

5. Outdated Security Comments

Security measures that changed but comments describing old behavior. Attackers exploit the difference.

6. Commenting on Security Bugs

Describing specific vulnerabilities in comments. Use private issue tracking instead.

7. Over-Documenting Attack Surface

Providing too much detail about how the system is vulnerable.

Practice Questions

1. What should security comments document?

Why security measures exist, what threats they protect against, assumptions, and failure modes.

2. What should security comments NOT document?

How to bypass measures, specific vulnerabilities, security weaknesses, or secrets.

3. Why might security comments be dangerous?

They can reveal information that helps attackers design exploits.

4. How should unresolved security issues be documented?

Reference a security ticket number. Do not describe the vulnerability in the comment.

5. Challenge: Review a security-critical source file for comment quality. Identify any comments that reveal too much or too little. Rewrite them safely.

FAQ

Mini Project

Review the comments in a security-critical module for safety. Identify any comments that reveal too much about attack surface or bypass methods. Rewrite them to document security purpose without revealing exploitable details.

What's Next

Next: Commenting Capstone Project