The Difference Between Guidelines With and Without a Modernize Analyzer

Guidelines with a modernize analyzer include automated static-analysis rules that detect patterns and suggest fixes, while guidelines without one remain documentation-only recommendations that developers must apply manually.

The JetBrains/go-modern-guidelines repository categorizes every Go best practice using a structured record that determines whether the rule can be enforced automatically. Understanding the difference between guidelines with and without a modernize analyzer helps teams decide which recommendations require manual code review and which can be caught by continuous integration tools.

How Guidelines Are Structured in the Source Code

At the core of the repository, every guideline is defined as a modernGoGuideline struct in internal/guidelines/guidelines.go. This struct contains metadata about the recommendation, including when it was introduced and—crucially—whether an automated checker exists.

type modernGoGuideline struct {
    id           string
    sinceVersion string
    modernizer   bool   // <‑‑ true ⇢ has a static‑analysis rule
    ...
}

The modernizer boolean field acts as the gatekeeper. It is populated from the embedded guidelines.json file (specifically the modernizer key in each entry) and consumed by both the CLI tools and the external analyzer to determine automation capabilities.

Guidelines With Modernize Support (modernizer: true)

When the modernizer field is set to true, the guideline is backed by the Go Modernize Analyzer, a separate static-analysis tool. This enables several automated workflows:

• IDE integrations that highlight violations in real-time
• go vet-style command-line checks during builds
• Automated fixes that rewrite code to match the "after" examples

The analyzer reads the same guidelines.json file and generates a corresponding golang.org/x/tools/go/analysis rule for every entry where modernizer is true. You can run these checks explicitly:

# The analyzer automatically warns about "modernizer"-enabled rules

go run github.com/JetBrains/go-modern-analyzer@latest ./...

Guidelines Without Modernize Support (modernizer: false)

When the modernizer field is false, the guideline exists only as documentation. The CLI can list and explain these rules using the list or explain commands, but the analyzer has no rule that can flag the issue in source code. Developers must read the recommendation and apply the advice manually.

// Example: printing a guideline that does **not** have an analyzer rule
fmt.Println(guideline.details) // read-only advice, no automatic detection

These guidelines still provide value as educational resources and coding standards, but they require human review to enforce.

Filtering for Analyzer-Compatible Guidelines Programmatically

The internal/cli/cli.go file demonstrates how tools can filter guidelines to show only those supported by static analysis. The ListAnalyzerSupported function filters the complete set of guidelines to return only entries where modernizer equals true and the target Go version is compatible:

// returns the textual list of guidelines that the analyzer can check
func ListAnalyzerSupported(targetGoVersion string) string {
    // filter to guidelines where modernizer == true
    var supported []modernGoGuideline
    for _, g := range modernGoGuidelines {
        if g.modernizer && goversion.Compare(targetGoVersion, g.sinceVersion) >= 0 {
            supported = append(supported, g)
        }
    }
    return toGuidelinesText(supported)
}

This filtering mechanism ensures that CI pipelines and developer tools only attempt to validate rules that have corresponding detection logic.

Schema and CLI Integration

The JSON schema definition in internal/guidelines/schema/schema.go formalizes the modernizer field, ensuring consistent data across the embedded guidelines.json file. The CLI entry point in internal/cli/cli.go uses this flag to differentiate between actionable checks and informational advice when responding to user queries.

The core library simply carries the boolean along; the actual rule generation happens in the external analyzer, which reads the same JSON source to build its check suite. This separation of concerns keeps the guideline definitions lightweight while allowing the analyzer to focus purely on the rules marked for automation.

Summary

• Guidelines with modernizer: true are enforced by the Go Modernize Analyzer through golang.org/x/tools/go/analysis rules, enabling automatic detection and fixes via IDE integrations and command-line tools.
• Guidelines with modernizer: false are documentation-only records that provide best-practice advice but require manual implementation.
• The modernGoGuideline struct in internal/guidelines/guidelines.go stores this distinction in the modernizer boolean field, populated from guidelines.json.
• The ListAnalyzerSupported function demonstrates how to programmatically filter for automated-check-compatible guidelines.
• The CLI and external analyzer both consume the same schema-defined data to present consistent information about which rules can be automatically validated.

Frequently Asked Questions

How do I know if a specific guideline has modernize analyzer support?

Check the modernizer field in the guideline's JSON entry. When using the CLI from internal/cli/cli.go, guidelines with analyzer support are explicitly filtered and listed separately from documentation-only recommendations. The boolean is stored in the modernGoGuideline struct and rendered in the ListAnalyzerSupported output.

Can I add automated checking to a guideline that currently lacks it?

Yes, but this requires creating a new golang.org/x/tools/go/analysis rule in the separate Go Modernize Analyzer tool, then updating the modernizer field to true in guidelines.json. The schema in internal/guidelines/schema/schema.go validates this field, and the core library in internal/guidelines/guidelines.go will automatically expose the updated status to the CLI.

Why do some guidelines remain documentation-only?

Not all coding patterns can be detected reliably through static analysis without false positives. Guidelines that depend on context-specific judgment, architectural decisions, or subjective style choices remain as modernizer: false to avoid incorrect automated fixes, serving instead as educational references for code reviewers.

How does the analyzer access the guideline definitions?

The analyzer reads the same embedded guidelines.json file that the CLI uses. It filters for entries where modernizer is true and generates corresponding analysis rules. This ensures that the detection logic and the documentation always remain synchronized according to the schema defined in internal/guidelines/schema/schema.go.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}