Code Documentation Standards

Apply Google Style documentation standards to Python (docstrings), Go (comments), TypeScript (JSDoc), and Terraform (descriptions). Ensures consistent, professional, and comprehensive code documentation across multiple languages.

When to Apply This Skill

Use this skill when:

• Writing new functions, classes, or packages
• Reviewing code for documentation quality
• User requests "document this code" or "add docstrings"
• User mentions "Google Style" or documentation standards
• Refactoring code that lacks proper documentation
• Creating code examples that should be well-documented

Core Principles

1. Clarity: Documentation should be immediately understandable
2. Completeness: Document all public APIs, parameters, returns, exceptions
3. Consistency: Follow language-specific Google Style conventions
4. Conciseness: Be thorough but avoid redundancy
5. Examples: Include usage examples for complex functionality

Workflow

1. Detect Language

Identify the programming language:

• Python: Look for .py files, def, class keywords, type hints
• Go: Look for .go files, func, type, package keywords
• TypeScript: Look for .ts / .tsx files, interface, type, export, import keywords
• Terraform: Look for .tf files, resource, variable, module keywords

2. Apply Appropriate Standard

Read the corresponding reference file:

• Python: Read references/python_google_style.md for complete docstring standards
• Go: Read references/go_google_style.md for complete comment standards
• TypeScript: Read references/typescript_google_style.md for complete JSDoc standards
• Terraform: Read references/terraform_style.md for complete description standards

3. Document Code Elements

Apply documentation to all appropriate code elements:

Python:

• Module-level docstrings
• Class docstrings
• Method/function docstrings
• Important variables/constants

Go:

• Package comments
• Type comments
• Function comments
• Important constants/variables

TypeScript:

• @fileoverview JSDoc (file-level)
• Interface and type alias JSDoc
• Class and constructor JSDoc
• Method and function JSDoc
• Exported constants and enums

Terraform:

• Variable descriptions
• Output descriptions
• Resource comments
• Module descriptions

4. Quality Checks

Before finalizing, verify:

• All public APIs are documented
• Parameters and returns are described
• Exceptions/errors are documented
• Examples are provided for complex functions
• Formatting follows Google Style exactly
• No redundant or obvious documentation

5. Provide Feedback

When reviewing code:

• Point out missing documentation
• Suggest improvements to existing docs
• Provide corrected examples
• Explain why certain documentation is important

Documentation Coverage

Python - What to Document

Always Document:

• Public modules (module-level docstring)
• Public classes (class docstring)
• Public methods and functions (method docstring)
• __init__ methods (explain parameters)

Consider Documenting:

• Complex private functions (with leading underscore)
• Non-obvious class attributes
• Module-level constants

Don't Document:

• Self-explanatory code (e.g., simple getters/setters)
• Override methods that just call super() without changes
• Trivial one-liner functions with obvious behavior

Go - What to Document

Always Document:

• Package (package comment before package declaration)
• Exported types (structs, interfaces)
• Exported functions and methods
• Exported constants and variables

Consider Documenting:

• Complex unexported functions
• Non-obvious implementation details
• Important internal structures

Don't Document:

• Trivial getters/setters
• Self-explanatory code
• Override methods without new behavior

TypeScript - What to Document

Always Document:

• All exported functions, classes, interfaces, type aliases, and enums
• Constructor parameters when using parameter properties (via @param)
• Class properties that are not self-evident from their names
• Thrown errors (@throws)
• Non-trivial return values (@returns)

Consider Documenting:

• Complex private methods (use // inline comments, not JSDoc)
• Non-obvious type constraints or invariants
• Performance characteristics of algorithms
• Side effects of functions

Don't Document:

• Trivial getters/setters where the name is fully self-explanatory
• Override methods that purely delegate to super without changes
• Implementation details already obvious from types and code

Terraform - What to Document

Always Document:

• All variables (description field)
• All outputs (description field)
• Module purpose (README.md)
• Complex resources (inline comments)

Consider Documenting:

• Data sources with complex filters
• Non-obvious resource dependencies
• Conditional resource creation logic

Don't Document:

• Self-explanatory variable names
• Simple pass-through outputs
• Standard resource configurations

Special Cases

Python Type Hints

When using type hints, docstrings can be more concise:

def add(a: int, b: int) -> int:
    """Add two integers.

    Args:
        a: First integer.
        b: Second integer.

    Returns:
        The sum of a and b.
    """
    return a + b

Type information is already in the signature, so Args and Returns can be brief.

Go Error Returns

Always document what errors a function can return:

// ReadConfig reads and parses the configuration file.
//
// Returns an error if the file cannot be read or contains invalid YAML.
func ReadConfig(path string) (*Config, error) {
    // implementation
}

TypeScript JSDoc and Type Hints

With TypeScript, types are enforced by the compiler so JSDoc should focus on semantics, not re-stating types. Use @param, @returns, and @throws:

/**
 * Fetches user profile data from the remote API.
 *
 * @param userId - Unique identifier for the user (UUID or numeric ID).
 * @returns Promise resolving to the user's profile.
 * @throws {HttpError} On non-2xx HTTP responses.
 * @throws {TimeoutError} If the request exceeds the configured timeout.
 *
 * @example
 * ```ts
 * const profile = await fetchUserProfile('user-123');
 * console.log(profile.displayName);
 * ```
 */
export async function fetchUserProfile(userId: string): Promise<UserProfile> {
  // implementation
}

Named exports only – never export default. File-level @fileoverview when the module's purpose is not obvious from its name.

Complex Algorithms

For complex logic, add inline comments AND comprehensive function documentation:

def dijkstra(graph: Graph, start: Node) -> dict[Node, float]:
    """Find shortest paths using Dijkstra's algorithm.

    Implements Dijkstra's single-source shortest path algorithm
    using a priority queue for O((V + E) log V) complexity.

    Args:
        graph: Weighted graph with non-negative edge weights.
        start: Starting node for path calculations.

    Returns:
        Dictionary mapping each node to its shortest distance from start.
        Unreachable nodes are not included in the result.

    Raises:
        ValueError: If graph contains negative edge weights.

    Example:
        >>> graph = Graph()
        >>> graph.add_edge("A", "B", 4)
        >>> graph.add_edge("A", "C", 2)
        >>> distances = dijkstra(graph, "A")
        >>> distances["B"]
        4
    """
    # Implementation with inline comments for complex parts

Output Format

When adding documentation to code:

1. Present the documented code with proper formatting
2. Explain what was added if the changes are significant
3. Highlight any decisions made about what to document or not document

Avoid

• Generic or placeholder documentation ("This function does stuff")
• Redundant documentation that just repeats the cod