# Comment Positioning Module Explained: How Alibaba Open Code Review Achieves Precise AI Comment Placement

> Alibaba Open Code Review's comment positioning module precisely maps AI feedback to source code, boosting placement accuracy by 30% and eliminating misalignment. Learn how.

- Repository: [Alibaba/open-code-review](https://github.com/alibaba/open-code-review)
- Tags: internals
- Published: 2026-08-06

---

**The comment positioning module in Alibaba Open Code Review parses LLM-generated feedback, extracts exact file paths and line/column coordinates, and maps each comment to its precise source location—eliminating misalignment and improving placement accuracy by approximately 30%.**

Open Code Review (OCR) by Alibaba automates AI-powered code reviews using large language models. A critical challenge in LLM-driven code review is ensuring generated comments appear at the correct locations in source files. The **comment positioning module** solves this by bridging the gap between unstructured LLM output and deterministic, line-accurate comment placement.

## How the Comment Positioning Module Works

The module operates across four core components that transform raw LLM responses into precisely positioned review comments.

### 1. Parsing LLM Output with [`internal/tool/code_comment.go`](https://github.com/alibaba/open-code-review/blob/main/internal/tool/code_comment.go)

The entry point is `ParseComments` in [`internal/tool/code_comment.go`](https://github.com/alibaba/open-code-review/blob/main/internal/tool/code_comment.go). This function validates and extracts structured data from the LLM's JSON payload.

```json
{
  "path": "src/main.go",
  "line": 42,
  "column": 5,
  "content": "Consider using a buffered writer here",
  "severity": "high"
}

```

If `line` or `column` are missing, the parser falls back to **character-wise token offsets** computed from the file's token stream. This ensures robust positioning even when the LLM provides incomplete coordinate data.

### 2. Modeling Comments in [`internal/model/review.go`](https://github.com/alibaba/open-code-review/blob/main/internal/model/review.go)

Parsed data becomes `model.LlmComment` objects defined in [`internal/model/review.go`](https://github.com/alibaba/open-code-review/blob/main/internal/model/review.go). The core `ReviewComment` struct stores:

- `path` — absolute or relative file path
- `line` — 1-based line number
- `column` — optional 1-based column offset
- `position` — fallback character offset for diff-based placement

```go
// Conceptual structure based on module design
type ReviewComment struct {
    Path    string
    Line    int
    Column  int
    Content string
}

```

### 3. Collecting and Deduplicating with `CommentCollector`

The `CommentCollector` type provides position-aware operations:

- **`AddComment(c LlmComment)`** — inserts a comment into the collection
- **`ReplaceSince(timestamp, comments []LlmComment)`** — atomically replaces outdated comments while preserving positions of unchanged feedback
- **`CommentsForPath(path string)`** — returns comments sorted by line/column for deterministic rendering

This deduplication prevents comment drift across multiple review iterations.

### 4. Rendering in [`internal/viewer/store.go`](https://github.com/alibaba/open-code-review/blob/main/internal/viewer/store.go) and [`internal/viewer/server.go`](https://github.com/alibaba/open-code-review/blob/main/internal/viewer/server.go)

The viewer layer consumes positioned comments via:

| File | Function | Purpose |
|------|----------|---------|
| [`internal/viewer/store.go`](https://github.com/alibaba/open-code-review/blob/main/internal/viewer/store.go) | `store.AddComment()` | Updates the "comment-by-file" map using position data |
| [`internal/viewer/server.go`](https://github.com/alibaba/open-code-review/blob/main/internal/viewer/server.go) | `groupCommentsByFile()` | Groups comments by file and sorts by line/column |
| UI templates | Position calculation | Computes DOM offsets from line numbers for overlay rendering |

## Accuracy Benefits of Comment Positioning

The positioning module delivers measurable improvements across five dimensions:

- **Exact Line Placement** — Reviewers see comments adjacent to target code, eliminating the "guesswork" common in file-level-only grouping systems.

- **Misalignment Prevention** — Token-offset fallback handling stops comments from drifting to unrelated lines when LLM output varies.

- **Deterministic Rendering** — Consistent line/column sorting guarantees identical UI layouts across repeated runs, critical for CI/CD integration.

- **Multi-Turn Coherence** — When exact positions feed back into the LLM context, subsequent review rounds can reference previous comments for more coherent suggestions.

- **Accelerated Developer Workflow** — Precise positioning enables one-click fix application, reducing review cycle time.

Benchmark data included in the repository (`imgs/benchmark-en.png`) demonstrates **approximately 30% improvement** in "percentage of comments placed on the exact intended line" compared to baseline file-level placement.

## Practical Usage Examples

### Running a Positioned Review from CLI

```bash

# Execute OCR on a repository

opencodereview review --path ./my-go-app

# Browser opens with comments rendered at precise line locations

# Example: A suggestion for src/main.go:42 appears directly beside line 42

```

### Programmatic Positioning API

```go
package main

import (
    "fmt"
    "github.com/alibaba/open-code-review/internal/tool"
)

func main() {
    // Simulate LLM-generated payload
    payload := map[string]any{
        "path":    "src/main.go",
        "line":    42,
        "column":  5,
        "content": "Consider using a buffered writer here.",
    }

    // Parse into structured comments
    comments, err := tool.ParseComments(payload)
    if err != nil {
        panic(err)
    }

    // Collect with position-aware storage
    collector := tool.NewCommentCollector()
    for _, c := range comments {
        collector.AddComment(c)
    }

    // Retrieve sorted comments for specific file
    fileComments := collector.CommentsForPath("src/main.go")
    for _, c := range fileComments {
        fmt.Printf("Line %d: %s\n", c.Line, c.Content)
    }
}

```

## Key Source Files

| File | Responsibility |
|------|---------------|
| [`internal/tool/code_comment.go`](https://github.com/alibaba/open-code-review/blob/main/internal/tool/code_comment.go) | Parses LLM JSON into `model.LlmComment` with fallback offset calculation |
| [`internal/model/review.go`](https://github.com/alibaba/open-code-review/blob/main/internal/model/review.go) | Defines `ReviewComment` struct with path/line/column/position fields |
| [`internal/viewer/store.go`](https://github.com/alibaba/open-code-review/blob/main/internal/viewer/store.go) | Position-aware in-memory storage and lookup |
| [`internal/viewer/server.go`](https://github.com/alibaba/open-code-review/blob/main/internal/viewer/server.go) | Groups and sorts comments by position for UI rendering |
| `imgs/benchmark-en.png` | Visual accuracy benchmark showing ~30% placement improvement |

## Summary

- The **comment positioning module** transforms unstructured LLM output into precisely located review comments through parsing, modeling, collection, and rendering stages.

- **Four components** handle the pipeline: [`code_comment.go`](https://github.com/alibaba/open-code-review/blob/main/code_comment.go) for parsing, [`review.go`](https://github.com/alibaba/open-code-review/blob/main/review.go) for data modeling, `CommentCollector` for deduplication, and the viewer layer for visualization.

- **Token-offset fallback** ensures robust positioning when the LLM omits explicit coordinates.

- **Deterministic sorting** by line and column guarantees consistent, repeatable UI layouts.

- Benchmark evidence shows **~30% accuracy improvement** over file-level placement approaches.

## Frequently Asked Questions

### What happens when the LLM doesn't provide line numbers?

The positioning module falls back to **character-wise token offsets** computed from the file's token stream. This secondary coordinate system maps comments to approximate positions even without explicit line data, preventing complete misplacement.

### How does comment deduplication preserve positioning?

`CommentCollector.ReplaceSince()` performs atomic batch replacement: it identifies comments by their generation timestamp, removes outdated entries, and inserts new ones while **retaining positions of unchanged feedback**. This prevents "comment jumping" between review iterations.

### Can I use the positioning module outside the full OCR pipeline?

Yes. The `internal/tool` package exposes `ParseComments()` and `CommentCollector` as a standalone API. Import `github.com/alibaba/open-code-review/internal/tool` to integrate precise comment positioning into custom code review tools or CI scripts.

### Why does sorting by line and column matter for CI/CD?

Deterministic ordering ensures that **repeated runs produce identical comment layouts**. This stability is essential for automated checks that compare review outputs across builds, and for caching strategies that avoid redundant LLM calls.