How to Get Detailed Explanations and Examples for Go Guideline IDs

Access the internal/guidelines/guidelines.json file directly, use the go-modern-guidelines show <id> CLI command, or import the internal/guidelines package to programmatically retrieve structured guideline data including descriptions, severity levels, and before/after code snippets.

The JetBrains/go-modern-guidelines repository encodes modern Go best practices as machine-readable structured data. Each guideline is identified by a unique string ID and contains detailed architectural explanations alongside concrete migration examples. Whether you need to look up a specific rule in your terminal, integrate the data into a custom tool, or browse the raw JSON, the repository provides three distinct access patterns.

Understanding the Guideline Data Structure

All guideline metadata lives in internal/guidelines/guidelines.json. This file contains an array of guideline objects, each structured with the following fields:

• id: The unique identifier string (e.g., slices_contains)
• guideline: Short rule summary
• details: Comprehensive architectural explanation
• impact: Severity classification (e.g., "Critical", "High")
• category: Logical grouping (e.g., "Collections", "Error Handling")
• since_version: Go version that introduced the modern alternative
• examples: Array of objects containing before and after code snippet arrays

A typical entry looks like this:

{
  "id": "slices_contains",
  "since_version": "1.21",
  "modernizer": true,
  "category": "Collections",
  "impact": "Critical",
  "guideline": "Use `slices.Contains` instead of a manual search loop.",
  "details": "...",
  "examples": [{ "before": [...], "after": [...] }]
}

Method 1: Direct JSON Lookup

For quick manual inspection, search the raw JSON file using standard command-line tools or your IDE. This method requires no installation and works immediately after cloning the repository.

Open internal/guidelines/guidelines.json and locate the target ID:

grep -A 20 '"id": "slices_contains"' internal/guidelines/guidelines.json

This approach returns the complete JSON object including all nested examples. Use your editor's JSON folding or a tool like jq to format the output for easier reading.

Method 2: Using the CLI Tool

The repository ships with a command-line interface defined in internal/cli/cli.go. Install the binary to query specific guideline IDs with formatted output.

First, install the tool:

go install github.com/JetBrains/go-modern-guidelines/cmd/go-modern-guidelines@latest

Or use the development script:

make dev-install

Then display any guideline by ID:

go-modern-guidelines show slices_contains

The CLI parses internal/guidelines/guidelines.json and renders the guideline text, details, and code examples in a terminal-friendly format.

Method 3: Programmatic Access

Import the internal/guidelines package to consume guideline data within Go applications. The package exports LoadGuidelines(), which returns a slice of Guideline structs mapped directly to the JSON schema.

package main

import (
    "fmt"
    "log"
    "strings"

    "github.com/JetBrains/go-modern-guidelines/internal/guidelines"
)

func main() {
    gs, err := guidelines.LoadGuidelines()
    if err != nil {
        log.Fatalf("load guidelines: %v", err)
    }

    id := "slices_contains"
    for _, g := range gs {
        if g.ID == id {
            fmt.Printf("Guideline %s (since %s):\n%s\n\nDetails:\n%s\n\n", 
                g.ID, g.SinceVersion, g.Guideline, g.Details)
            
            for i, ex := range g.Examples {
                fmt.Printf("--- Example %d ---\nBefore:\n%s\nAfter:\n%s\n\n",
                    i+1,
                    strings.Join(ex.Before, "\n"),
                    strings.Join(ex.After, "\n"))
            }
        }
    }
}

This pattern enables automation such as custom linting tools, documentation generators, or IDE integrations that need structured access to the guideline definitions.

Summary

• Raw data source: All guidelines reside in internal/guidelines/guidelines.json with fields for id, guideline, details, and nested examples arrays.
• CLI access: Install via go install and run go-modern-guidelines show <ID> for formatted terminal output based on internal/cli/cli.go.
• Programmatic API: Import internal/guidelines and call LoadGuidelines() to retrieve typed structs for custom tooling.
• Schema: Each guideline includes since_version, impact level, category, and paired before/after code snippets.

Frequently Asked Questions

How do I find the ID for a specific guideline?

Browse internal/guidelines/guidelines.json and look for the "id" field values, or use the CLI without arguments to list available guidelines. The ID typically reflects the Go feature or pattern being addressed (e.g., maps_clone, slices_sort).

Can I use this data in my own Go analysis tools?

Yes. Import github.com/JetBrains/go-modern-guidelines/internal/guidelines and call LoadGuidelines() to access the full dataset as Go structs. The Guideline type exposes all JSON fields including Examples, which contains Before and After string slices.

What Go version added the slices.Contains function?

According to the repository data, the slices_contains guideline specifies "since_version": "1.21", indicating that slices.Contains was introduced in Go 1.21. Each guideline records the version when the modern alternative became available in the standard library.

Where is the CLI tool source code located?

The command-line implementation resides in internal/cli/cli.go. This file handles argument parsing and formats the guideline data from internal/guidelines/guidelines.json for terminal display.

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