Skip to content

Comments Analyzer

The comments analyzer evaluates documentation coverage by examining comment presence, placement, and density across your source code. It identifies functions and classes that lack documentation and measures overall documentation quality.

Quick Start

uast parse main.go | codefang analyze -a comments

Or analyze an entire directory:

codefang analyze -a comments ./src/

What It Measures

Documentation Coverage

The percentage of public functions, methods, and classes that have an associated documentation comment. A comment is "associated" when it immediately precedes the declaration.

Comment Placement Quality

Not all comments are equally useful. The analyzer distinguishes:

  • Doc comments: Comments immediately before a function/class declaration
  • Inline comments: Comments within function bodies
  • Orphan comments: Comments not associated with any code structure

Comment Density

The ratio of comment lines to total lines of code. Provides a quick overall measure of how well-documented a file is.

Healthy ratios

A comment density between 15-30% is generally considered healthy. Below 10% suggests under-documentation; above 40% may indicate stale or redundant comments.

Configuration Options

The comments analyzer uses the UAST directly and has no analyzer-specific configuration options.

Option Type Default Description
(none) -- -- Uses UAST; no analyzer-specific config

Example Output

{
  "comments": {
    "files": [
      {
        "file": "main.go",
        "total_lines": 250,
        "comment_lines": 45,
        "comment_density": 0.18,
        "functions_total": 12,
        "functions_documented": 8,
        "documentation_coverage": 0.67,
        "undocumented": [
          {"name": "helperFunc", "line": 89},
          {"name": "processItem", "line": 134},
          {"name": "cleanup", "line": 201},
          {"name": "retryLoop", "line": 220}
        ]
      }
    ],
    "summary": {
      "total_files": 1,
      "avg_comment_density": 0.18,
      "avg_documentation_coverage": 0.67,
      "total_undocumented_functions": 4
    }
  }
}

Documentation Coverage
  main.go
    density=18%  coverage=67% (8/12 functions documented)
    undocumented: helperFunc:89 processItem:134 cleanup:201 retryLoop:220

Summary: 1 file, avg density=18%, avg coverage=67%

Use Cases

  • Documentation enforcement: Require minimum documentation coverage in CI/CD pipelines.
  • Onboarding assessment: Measure how well-documented a codebase is before new team members join.
  • API surface quality: Ensure all exported/public functions have doc comments.
  • Stale comment detection: Identify files with unusually high comment density that may contain outdated comments.

Limitations

  • Comment quality: The analyzer measures comment presence and placement, not comment quality. A comment saying // do the thing counts the same as a thorough description.
  • Language conventions: Documentation comment conventions vary by language (e.g., /// in Rust, """ in Python, // in Go). The UAST normalizes these, but edge cases in less common languages may be missed.
  • Auto-generated docs: Comments generated by tools (e.g., protobuf stubs) are counted the same as hand-written documentation.
  • Multilingual comments: Comment text is not analyzed for language quality or correctness.