comments

package
v1.0.0-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 13, 2026 License: Apache-2.0, Apache-2.0 Imports: 19 Imported by: 0

README

Comments Analysis

Preface

Code tells you how, but comments tell you why. Good documentation is essential for long-term project maintainability.

Problem

It's easy to write code and forget to document it. Over time, this leads to a codebase where the intent is lost, making onboarding difficult and increasing the risk of bugs during modification. Conversely, too many trivial comments can clutter the code.

How analyzer solves it

The Comments analyzer scans the codebase to evaluate the density, placement, and "quality" of comments. It checks if functions and classes are documented and if comments are placed correctly (e.g., immediately preceding the target).

Historical context

Documentation coverage is a standard metric in CI/CD pipelines (e.g., Golint, Javadoc checks). This analyzer generalizes it across languages using UAST.

Real world examples

  • Documentation Audits: Identifying critical modules that lack documentation.
  • Code Quality Gates: Preventing code with low documentation coverage from being merged.

How analyzer works here

  1. Node Identification: Finds all comment nodes and function/method/class nodes in the UAST.
  2. Association: Heuristically associates comments with the nearest logical code block (e.g., a function definition) based on line numbers.
  3. Metrics Calculation:
    • Documentation Coverage: % of functions with associated comments.
    • Placement Score: Are comments "orphaned" or attached to code?
    • Length Checks: Filters out trivial/short comments.

Limitations

  • Content Analysis: It checks for the presence and placement of comments, but doesn't deeply "read" them to judge if they make sense (though sentiment analysis is a separate analyzer).
  • Heuristics: Association is distance-based and might misattribute comments in complex layouts.

Further plans

  • NLP integration to detect "comment rot" (comments that contradict the code).
  • Support for detecting specific documentation standards (e.g., Javadoc vs. Doxygen).

Documentation

Overview

Package comments provides comments functionality.

Index

Constants

View Source 
const (
	DocScoreThresholdGood = 0.6
	DocScoreThresholdFair = 0.3
)

Documentation score thresholds and constants.

View Source 
const (
	SectionTitle = "COMMENTS"

	// MetricTotalComments and related constants define metric labels.
	MetricTotalComments  = "Total Comments"
	MetricGoodComments   = "Good Comments"
	MetricBadComments    = "Bad Comments"
	MetricDocCoverage    = "Doc Coverage"
	MetricGoodRatio      = "Good Ratio"
	MetricTotalFunctions = "Total Functions"

	// DistLabelDocumented is the distribution label for documented functions.
	DistLabelDocumented   = "Documented"
	DistLabelUndocumented = "Undocumented"

	// IssueAssessmentBad is the assessment value indicating a function has no comment.
	IssueAssessmentBad = "❌ No Comment"
	IssueValueNoDoc    = "undocumented"

	// KeyOverallScore is the report key for the overall comments score.
	KeyOverallScore   = "overall_score"
	KeyTotalComments  = "total_comments"
	KeyGoodComments   = "good_comments"
	KeyBadComments    = "bad_comments"
	KeyDocCoverage    = "documentation_coverage"
	KeyGoodRatio      = "good_comments_ratio"
	KeyTotalFunctions = "total_functions"
	KeyDocFunctions   = "documented_functions"
	KeyMessage        = "message"
	KeyFunctions      = "functions"
	KeyFuncName       = "function"
	KeyFuncAssessment = "assessment"

	// DefaultStatusMessage is the fallback message when no comment data is available.
	DefaultStatusMessage = "No comment data available"
)

Section rendering constants.

View Source 
const (
	MaxDepthValue = 10
)

MaxDepthValue is the default maximum UAST traversal depth for comment analysis.

View Source 
const (
	// ScoreValue is the base penalty applied when a comment quality issue is detected.
	ScoreValue = 0.2
)

Configuration constants for comment analysis scoring.

Variables

View Source 
var ErrInvalidFunctionsData = errors.New("invalid comments report: expected []map[string]any for functions")

ErrInvalidFunctionsData indicates the report doesn't contain expected functions data.

Functions

func RegisterPlotSections 

func RegisterPlotSections()

RegisterPlotSections registers the comments plot section renderer with the analyze package.

Types

type AggregateData 

type AggregateData struct {
	TotalComments         int     `json:"total_comments"         yaml:"total_comments"`
	GoodComments          int     `json:"good_comments"          yaml:"good_comments"`
	BadComments           int     `json:"bad_comments"           yaml:"bad_comments"`
	OverallScore          float64 `json:"overall_score"          yaml:"overall_score"`
	TotalFunctions        int     `json:"total_functions"        yaml:"total_functions"`
	DocumentedFunctions   int     `json:"documented_functions"   yaml:"documented_functions"`
	GoodCommentsRatio     float64 `json:"good_comments_ratio"    yaml:"good_comments_ratio"`
	DocumentationCoverage float64 `json:"documentation_coverage" yaml:"documentation_coverage"`
	HealthScore           float64 `json:"health_score"           yaml:"health_score"`
	Message               string  `json:"message"                yaml:"message"`
}

AggregateData contains summary statistics.

type AggregateMetric 

type AggregateMetric struct {
	metrics.MetricMeta
}

AggregateMetric computes summary statistics.

func NewAggregateMetric 

func NewAggregateMetric() *AggregateMetric

NewAggregateMetric creates the aggregate metric.

func (*AggregateMetric) Compute 

func (m *AggregateMetric) Compute(input *ReportData) AggregateData

Compute calculates aggregate statistics.

type Aggregator 

type Aggregator struct {
	*common.Aggregator
	common.PerFileRetainer
	// contains filtered or unexported fields
}

Aggregator aggregates results from multiple comment analyses.

func NewAggregator 

func NewAggregator() *Aggregator

NewAggregator creates a new Aggregator.

func (*Aggregator) Aggregate 

func (ca *Aggregator) Aggregate(results map[string]analyze.Report)

Aggregate overrides the base Aggregate method to collect detailed comments and functions.

func (*Aggregator) GetResult 

func (ca *Aggregator) GetResult() analyze.Report

GetResult overrides the base GetResult method to include detailed comments and functions.

func (*Aggregator) SetAggregationMode 

func (ca *Aggregator) SetAggregationMode(mode analyze.AggregationMode)

SetAggregationMode propagates the mode to both the base aggregator and the detailed data collector.

type Analyzer 

type Analyzer struct {
	// contains filtered or unexported fields
}

Analyzer provides comment placement analysis.

func NewAnalyzer 

func NewAnalyzer() *Analyzer

NewAnalyzer creates a new Analyzer with generic components.

func (*Analyzer) Analyze 

func (c *Analyzer) Analyze(root *node.Node) (analyze.Report, error)

Analyze performs comment analysis using default configuration.

func (*Analyzer) Configure 

func (c *Analyzer) Configure(_ map[string]any) error

Configure configures the analyzer.

func (*Analyzer) CreateAggregator 

func (c *Analyzer) CreateAggregator() analyze.ResultAggregator

CreateAggregator creates a new aggregator for comment analysis.

func (*Analyzer) CreateReportSection 

func (c *Analyzer) CreateReportSection(report analyze.Report) analyze.ReportSection

CreateReportSection creates a ReportSection from report data.

func (*Analyzer) CreateVisitor 

func (c *Analyzer) CreateVisitor() analyze.AnalysisVisitor

CreateVisitor creates a new visitor for comments analysis.

func (*Analyzer) DefaultConfig 

func (c *Analyzer) DefaultConfig() CommentConfig

DefaultConfig returns the default configuration for comment analysis.

func (*Analyzer) Description 

func (c *Analyzer) Description() string

Description returns the analyzer description.

func (*Analyzer) Descriptor 

func (c *Analyzer) Descriptor() analyze.Descriptor

Descriptor returns stable analyzer metadata.

func (*Analyzer) Flag 

func (c *Analyzer) Flag() string

Flag returns the CLI flag for the analyzer.

func (*Analyzer) FormatReport 

func (c *Analyzer) FormatReport(report analyze.Report, w io.Writer) error

FormatReport formats comment analysis results as human-readable text.

func (*Analyzer) FormatReportBinary 

func (c *Analyzer) FormatReportBinary(report analyze.Report, w io.Writer) error

FormatReportBinary formats comment analysis results as binary envelope.

func (*Analyzer) FormatReportJSON 

func (c *Analyzer) FormatReportJSON(report analyze.Report, w io.Writer) error

FormatReportJSON formats comment analysis results as JSON.

func (*Analyzer) FormatReportPlot 

func (c *Analyzer) FormatReportPlot(report analyze.Report, w io.Writer) error

FormatReportPlot generates an HTML plot visualization for comments analysis.

func (*Analyzer) FormatReportYAML 

func (c *Analyzer) FormatReportYAML(report analyze.Report, w io.Writer) error

FormatReportYAML formats comment analysis results as YAML.

func (*Analyzer) ListConfigurationOptions 

func (c *Analyzer) ListConfigurationOptions() []pipeline.ConfigurationOption

ListConfigurationOptions returns the configuration options for the analyzer.

func (*Analyzer) Name 

func (c *Analyzer) Name() string

Name returns the analyzer name.

func (*Analyzer) Thresholds 

func (c *Analyzer) Thresholds() analyze.Thresholds

Thresholds returns the quality thresholds for this analyzer.

type CommentBlock 

type CommentBlock struct {
	FullText  string
	Comments  []*node.Node
	StartLine int
	EndLine   int
}

CommentBlock represents a group of consecutive comment lines.

type CommentConfig 

type CommentConfig struct {
	PenaltyScores    map[string]float64
	RewardScore      float64
	MaxCommentLength int
}

CommentConfig holds configuration for comment analysis.

type CommentData 

type CommentData struct {
	LineNumber     int
	SourceFile     string
	Language       string
	Directory      string
	Quality        string
	Type           string
	TargetType     string
	TargetName     string
	Position       string
	Recommendation string
	Score          float64
}

CommentData holds data for a single comment.

type CommentDetail 

type CommentDetail struct {
	Quality        string  `json:"quality"`
	Token          string  `json:"token"`
	Position       string  `json:"position"`
	Type           string  `json:"type"`
	Recommendation string  `json:"recommendation"`
	TargetType     string  `json:"target_type"`
	TargetName     string  `json:"target_name"`
	Score          float64 `json:"score"`
	StartLine      int     `json:"start_line"`
	EndLine        int     `json:"end_line"`
	Length         int     `json:"length"`
	LineNumber     int     `json:"line_number"`
	IsGood         bool    `json:"is_good"`
}

CommentDetail holds information about a specific comment.

type CommentMetrics 

type CommentMetrics struct {
	FunctionSummary     map[string]FunctionInfo `json:"function_summary"`
	CommentDetails      []CommentDetail         `json:"comment_details"`
	TotalComments       int                     `json:"total_comments"`
	GoodComments        int                     `json:"good_comments"`
	BadComments         int                     `json:"bad_comments"`
	OverallScore        float64                 `json:"overall_score"`
	TotalFunctions      int                     `json:"total_functions"`
	DocumentedFunctions int                     `json:"documented_functions"`
}

CommentMetrics holds comment analysis results.

type CommentQualityData 

type CommentQualityData struct {
	LineNumber     int     `json:"line_number"              yaml:"line_number"`
	SourceFile     string  `json:"source_file,omitempty"    yaml:"source_file,omitempty"`
	Language       string  `json:"language,omitempty"       yaml:"language,omitempty"`
	Directory      string  `json:"directory,omitempty"      yaml:"directory,omitempty"`
	Quality        string  `json:"quality"                  yaml:"quality"`
	Type           string  `json:"type"                     yaml:"type"`
	TargetName     string  `json:"target_name"              yaml:"target_name"`
	Score          float64 `json:"score"                    yaml:"score"`
	Recommendation string  `json:"recommendation,omitempty" yaml:"recommendation,omitempty"`
}

CommentQualityData contains quality assessment for a comment.

type CommentQualityMetric 

type CommentQualityMetric struct {
	metrics.MetricMeta
}

CommentQualityMetric computes per-comment quality data.

func NewCommentQualityMetric 

func NewCommentQualityMetric() *CommentQualityMetric

NewCommentQualityMetric creates the comment quality metric.

func (*CommentQualityMetric) Compute 

func (m *CommentQualityMetric) Compute(input *ReportData) []CommentQualityData

Compute calculates comment quality data.

type CommentReportItem 

type CommentReportItem struct {
	Comment    string
	Placement  string
	Target     string
	Assessment string
	Line       int
}

CommentReportItem is a typed representation of a per-comment report item.

type ComputedMetrics 

type ComputedMetrics struct {
	CommentQuality        []CommentQualityData        `json:"comment_quality"        yaml:"comment_quality"`
	FunctionDocumentation []FunctionDocumentationData `json:"function_documentation" yaml:"function_documentation"`
	UndocumentedFunctions []UndocumentedFunctionData  `json:"undocumented_functions" yaml:"undocumented_functions"`
	Aggregate             AggregateData               `json:"aggregate"              yaml:"aggregate"`
}

ComputedMetrics holds all computed metric results for the comments analyzer.

func ComputeAllMetrics 

func ComputeAllMetrics(report analyze.Report) (*ComputedMetrics, error)

ComputeAllMetrics runs all comments metrics and returns the results.

func (*ComputedMetrics) AnalyzerName 

func (m *ComputedMetrics) AnalyzerName() string

AnalyzerName returns the name of the analyzer.

func (*ComputedMetrics) ToJSON 

func (m *ComputedMetrics) ToJSON() any

ToJSON returns the metrics as a JSON-serializable object.

func (*ComputedMetrics) ToYAML 

func (m *ComputedMetrics) ToYAML() any

ToYAML returns the metrics as a YAML-serializable object.

type FunctionCommentData 

type FunctionCommentData struct {
	Name         string
	SourceFile   string
	Language     string
	Directory    string
	HasComment   bool
	NeedsComment bool
	CommentScore float64
	CommentType  string
}

FunctionCommentData holds comment data for a function.

type FunctionDocumentationData 

type FunctionDocumentationData struct {
	Name               string  `json:"name"                  yaml:"name"`
	SourceFile         string  `json:"source_file,omitempty" yaml:"source_file,omitempty"`
	Language           string  `json:"language,omitempty"    yaml:"language,omitempty"`
	Directory          string  `json:"directory,omitempty"   yaml:"directory,omitempty"`
	IsDocumented       bool    `json:"is_documented"         yaml:"is_documented"`
	DocumentationScore float64 `json:"documentation_score"   yaml:"documentation_score"`
	Status             string  `json:"status"                yaml:"status"`
}

FunctionDocumentationData contains documentation status for a function.

type FunctionDocumentationMetric 

type FunctionDocumentationMetric struct {
	metrics.MetricMeta
}

FunctionDocumentationMetric computes per-function documentation status.

func NewFunctionDocumentationMetric 

func NewFunctionDocumentationMetric() *FunctionDocumentationMetric

NewFunctionDocumentationMetric creates the function documentation metric.

func (*FunctionDocumentationMetric) Compute 

func (m *FunctionDocumentationMetric) Compute(input *ReportData) []FunctionDocumentationData

Compute calculates function documentation data.

type FunctionInfo 

type FunctionInfo struct {
	Name          string  `json:"name"`
	Type          string  `json:"type"`
	CommentType   string  `json:"comment_type"`
	Documentation string  `json:"documentation"`
	StartLine     int     `json:"start_line"`
	EndLine       int     `json:"end_line"`
	CommentScore  float64 `json:"comment_score"`
	HasComment    bool    `json:"has_comment"`
	NeedsComment  bool    `json:"needs_comment"`
}

FunctionInfo holds information about a function.

type FunctionReportItem 

type FunctionReportItem struct {
	Function   string
	Type       string
	Comment    string
	Assessment string
	Lines      int
}

FunctionReportItem is a typed representation of a per-function report item.

type ReportData 

type ReportData struct {
	TotalComments         int
	GoodComments          int
	BadComments           int
	OverallScore          float64
	TotalFunctions        int
	DocumentedFunctions   int
	GoodCommentsRatio     float64
	DocumentationCoverage float64
	Comments              []CommentData
	Functions             []FunctionCommentData
	Message               string
}

ReportData is the parsed input data for comments metrics computation.

func ParseReportData 

func ParseReportData(report analyze.Report) (*ReportData, error)

ParseReportData extracts ReportData from an analyzer report.

type ReportSection 

type ReportSection struct {
	analyze.BaseReportSection
	// contains filtered or unexported fields
}

ReportSection implements analyze.ReportSection for comments analysis.

func NewReportSection 

func NewReportSection(report analyze.Report) *ReportSection

NewReportSection creates a ReportSection from a comments report.

func (*ReportSection) AllIssues 

func (s *ReportSection) AllIssues() []analyze.Issue

AllIssues returns all undocumented functions sorted by name.

func (*ReportSection) Distribution 

func (s *ReportSection) Distribution() []analyze.DistributionItem

Distribution returns documented vs undocumented function distribution.

func (*ReportSection) KeyMetrics 

func (s *ReportSection) KeyMetrics() []analyze.Metric

KeyMetrics returns the key metrics for the comments section.

func (*ReportSection) TopIssues 

func (s *ReportSection) TopIssues(n int) []analyze.Issue

TopIssues returns the top N undocumented functions sorted by name.

type UndocumentedFunctionData 

type UndocumentedFunctionData struct {
	Name         string `json:"name"                  yaml:"name"`
	SourceFile   string `json:"source_file,omitempty" yaml:"source_file,omitempty"`
	Language     string `json:"language,omitempty"    yaml:"language,omitempty"`
	Directory    string `json:"directory,omitempty"   yaml:"directory,omitempty"`
	NeedsComment bool   `json:"needs_comment"         yaml:"needs_comment"`
	RiskLevel    string `json:"risk_level"            yaml:"risk_level"`
}

UndocumentedFunctionData identifies functions lacking documentation.

type UndocumentedFunctionMetric 

type UndocumentedFunctionMetric struct {
	metrics.MetricMeta
}

UndocumentedFunctionMetric identifies functions lacking documentation.

func NewUndocumentedFunctionMetric 

func NewUndocumentedFunctionMetric() *UndocumentedFunctionMetric

NewUndocumentedFunctionMetric creates the undocumented function metric.

func (*UndocumentedFunctionMetric) Compute 

func (m *UndocumentedFunctionMetric) Compute(input *ReportData) []UndocumentedFunctionData

Compute identifies undocumented functions.

type Visitor 

type Visitor struct {
	// contains filtered or unexported fields
}

Visitor implements NodeVisitor for comment analysis.

func NewVisitor 

func NewVisitor() *Visitor

NewVisitor creates a new Visitor.

func (*Visitor) GetReport 

func (v *Visitor) GetReport() analyze.Report

GetReport returns the collected analysis report.

func (*Visitor) OnEnter 

func (v *Visitor) OnEnter(n *node.Node, _ int)

OnEnter is called when entering a node during AST traversal.

func (*Visitor) OnExit 

func (v *Visitor) OnExit(_ *node.Node, _ int)

OnExit is called when exiting a node during AST traversal.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.