Back to Details

code-annotation-patterns

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Annotation Patterns for AI Development

面向AI开发的代码注释模式

Advanced patterns for annotating code with structured metadata that supports AI-assisted development workflows.
为代码添加结构化元数据的高级模式，可支持AI辅助开发工作流。

Annotation Categories

注释分类

Technical Debt Markers

技术债务标记

Structured annotations for tracking technical debt:
typescript
/**
 * @ai-tech-debt
 * @category: Architecture
 * @severity: High
 * @effort: 2-3 days
 * @impact: Maintainability, Performance
 *
 * This service class has grown to 1500+ lines and violates Single
 * Responsibility Principle. Should be split into:
 * - UserAuthService (authentication logic)
 * - UserProfileService (profile management)
 * - UserPreferencesService (settings/preferences)
 *
 * Blocking new features: User role management (#234), SSO integration (#245)
 */
class UserService {
  // Implementation...
}
Severity levels:
  • Critical
    : Security vulnerabilities, data loss risks
  • High
    : Significant maintainability or performance issues
  • Medium
    : Code quality concerns, testing gaps
  • Low
    : Minor improvements, nice-to-haves
用于跟踪技术债务的结构化注释：
typescript
/**
 * @ai-tech-debt
 * @category: Architecture
 * @severity: High
 * @effort: 2-3 days
 * @impact: Maintainability, Performance
 *
 * This service class has grown to 1500+ lines and violates Single
 * Responsibility Principle. Should be split into:
 * - UserAuthService (authentication logic)
 * - UserProfileService (profile management)
 * - UserPreferencesService (settings/preferences)
 *
 * Blocking new features: User role management (#234), SSO integration (#245)
 */
class UserService {
  // Implementation...
}
严重程度等级：
  • Critical
    : 安全漏洞、数据丢失风险
  • High
    : 重大可维护性或性能问题
  • Medium
    : 代码质量问题、测试缺口
  • Low
    : 次要改进项、锦上添花的功能

Security Annotations

安全注释

python
undefined
python
undefined

@ai-security

@ai-security

@risk-level: High

@risk-level: High

@cwe: CWE-89 (SQL Injection)

@cwe: CWE-89 (SQL Injection)

@mitigation: Use parameterized queries

@mitigation: Use parameterized queries

SECURITY WARNING: This function constructs SQL queries dynamically.

SECURITY WARNING: This function constructs SQL queries dynamically.

Although input is validated, parameterized queries would be safer.

Although input is validated, parameterized queries would be safer.

Current validation regex: ^[a-zA-Z0-9_]+$

Current validation regex: ^[a-zA-Z0-9_]+$

TODO(ai/security): Migrate to SQLAlchemy ORM or use parameterized queries

TODO(ai/security): Migrate to SQLAlchemy ORM or use parameterized queries

def get_user_by_username(username: str): # Current implementation with string formatting query = f"SELECT * FROM users WHERE username = '{username}'"
undefined
def get_user_by_username(username: str): # Current implementation with string formatting query = f"SELECT * FROM users WHERE username = '{username}'"
undefined

Performance Annotations

性能注释

java
/**
 * @ai-performance
 * @complexity: O(n²)
 * @bottleneck: true
 * @profiling-data: 45% of request time when n > 100
 * @optimization-target: O(n log n) or better
 *
 * This nested loop is the primary performance bottleneck for large
 * datasets. Profiling shows:
 * - n=10: 5ms avg
 * - n=100: 120ms avg
 * - n=1000: 11s avg (unacceptable)
 *
 * Optimization approaches:
 * 1. Sort + binary search: O(n log n) - estimated 95% improvement
 * 2. Hash map: O(n) - best performance but higher memory usage
 * 3. Database-level optimization: Move logic to SQL query
 */
public List<Match> findMatches(List<Item> items) {
    // O(n²) implementation
}
java
/**
 * @ai-performance
 * @complexity: O(n²)
 * @bottleneck: true
 * @profiling-data: 45% of request time when n > 100
 * @optimization-target: O(n log n) or better
 *
 * This nested loop is the primary performance bottleneck for large
 * datasets. Profiling shows:
 * - n=10: 5ms avg
 * - n=100: 120ms avg
 * - n=1000: 11s avg (unacceptable)
 *
 * Optimization approaches:
 * 1. Sort + binary search: O(n log n) - estimated 95% improvement
 * 2. Hash map: O(n) - best performance but higher memory usage
 * 3. Database-level optimization: Move logic to SQL query
 */
public List<Match> findMatches(List<Item> items) {
    // O(n²) implementation
}

Accessibility Annotations

无障碍注释

typescript
/**
 * @ai-a11y
 * @wcag-level: AA
 * @compliance-status: Partial
 * @issues:
 *   - Missing ARIA labels for icon buttons
 *   - Insufficient color contrast (3.2:1, needs 4.5:1)
 *   - Keyboard navigation incomplete
 *
 * Component needs accessibility improvements to meet WCAG 2.1 Level AA.
 * Audit completed: 2025-12-04
 * Blocking: Public sector deployment (requires AA compliance)
 */
export function SearchBar() {
  // Implementation with partial a11y support
}
typescript
/**
 * @ai-a11y
 * @wcag-level: AA
 * @compliance-status: Partial
 * @issues:
 *   - Missing ARIA labels for icon buttons
 *   - Insufficient color contrast (3.2:1, needs 4.5:1)
 *   - Keyboard navigation incomplete
 *
 * Component needs accessibility improvements to meet WCAG 2.1 Level AA.
 * Audit completed: 2025-12-04
 * Blocking: Public sector deployment (requires AA compliance)
 */
export function SearchBar() {
  // Implementation with partial a11y support
}

Testing Annotations

测试注释

go
// @ai-testing
// @coverage: 45%
// @coverage-target: 80%
// @missing-tests:
//   - Edge case: nil pointer handling
//   - Edge case: Concurrent access scenarios
//   - Integration: Database transaction rollback
//
// Test coverage is below target. Priority areas:
// 1. Error handling paths (currently untested)
// 2. Concurrent access (identified race condition in PR review)
// 3. Database edge cases (transaction boundaries)

func ProcessOrder(order *Order) error {
    // Implementation with incomplete test coverage
}
go
// @ai-testing
// @coverage: 45%
// @coverage-target: 80%
// @missing-tests:
//   - Edge case: nil pointer handling
//   - Edge case: Concurrent access scenarios
//   - Integration: Database transaction rollback
//
// Test coverage is below target. Priority areas:
// 1. Error handling paths (currently untested)
// 2. Concurrent access (identified race condition in PR review)
// 3. Database edge cases (transaction boundaries)

func ProcessOrder(order *Order) error {
    // Implementation with incomplete test coverage
}

Semantic Tags

语义标签

Change Impact Tags

变更影响标签

typescript
/**
 * @ai-change-impact
 * @breaking-change: true
 * @affects:
 *   - API consumers (public method signature changed)
 *   - Database migrations (requires schema update)
 *   - Dependent services (contract modified)
 *
 * This change modifies the public API contract. Migration guide:
 * 1. Update API clients to use new parameter format
 * 2. Run migration script: ./scripts/migrate_v2_to_v3.sh
 * 3. Update environment variables (NEW_API_KEY required)
 *
 * Backward compatibility: Supported until v4.0.0 (2026-06-01)
 */
typescript
/**
 * @ai-change-impact
 * @breaking-change: true
 * @affects:
 *   - API consumers (public method signature changed)
 *   - Database migrations (requires schema update)
 *   - Dependent services (contract modified)
 *
 * This change modifies the public API contract. Migration guide:
 * 1. Update API clients to use new parameter format
 * 2. Run migration script: ./scripts/migrate_v2_to_v3.sh
 * 3. Update environment variables (NEW_API_KEY required)
 *
 * Backward compatibility: Supported until v4.0.0 (2026-06-01)
 */

Dependency Tags

依赖标签

python
undefined
python
undefined

@ai-dependency

@ai-dependency

@external-service: PaymentAPI

@external-service: PaymentAPI

@failure-mode: graceful-degradation

@failure-mode: graceful-degradation

@fallback: offline-payment-queue

@fallback: offline-payment-queue

@sla: 99.9% uptime

@sla: 99.9% uptime

@timeout: 5000ms

@timeout: 5000ms

This function depends on external payment service. Failure handling:

This function depends on external payment service. Failure handling:

- Timeout: Queue for retry, notify user of delayed processing

- Timeout: Queue for retry, notify user of delayed processing

- Service down: Queue for batch processing, store transaction locally

- Service down: Queue for batch processing, store transaction locally

- Invalid response: Log error, rollback transaction, notify monitoring

- Invalid response: Log error, rollback transaction, notify monitoring

Circuit breaker: Opens after 5 consecutive failures, half-open after 30s

Circuit breaker: Opens after 5 consecutive failures, half-open after 30s

async def process_payment(transaction: Transaction) -> PaymentResult: # Implementation with external service dependency
undefined
async def process_payment(transaction: Transaction) -> PaymentResult: // Implementation with external service dependency
undefined

Configuration Tags

配置标签

rust
/// @ai-config
/// @env-vars:
///   - DATABASE_URL (required)
///   - REDIS_URL (optional, falls back to in-memory cache)
///   - LOG_LEVEL (optional, default: "info")
/// @config-file: config/production.yaml
/// @secrets:
///   - API_SECRET_KEY (must be 32+ chars)
///   - JWT_PRIVATE_KEY (RSA 2048-bit minimum)
///
/// Configuration loading order:
/// 1. Environment variables (highest priority)
/// 2. config/{environment}.yaml files
/// 3. Default values (lowest priority)

pub struct AppConfig {
    // Configuration fields
}
rust
/// @ai-config
/// @env-vars:
///   - DATABASE_URL (required)
///   - REDIS_URL (optional, falls back to in-memory cache)
///   - LOG_LEVEL (optional, default: "info")
/// @config-file: config/production.yaml
/// @secrets:
///   - API_SECRET_KEY (must be 32+ chars)
///   - JWT_PRIVATE_KEY (RSA 2048-bit minimum)
///
/// Configuration loading order:
/// 1. Environment variables (highest priority)
/// 2. config/{environment}.yaml files
/// 3. Default values (lowest priority)

pub struct AppConfig {
    // Configuration fields
}

Annotation Formats

注释格式

Inline Annotations

行内注释

For single-line or small context:
javascript
// @ai-pattern: Singleton
// @ai-thread-safety: Not thread-safe, use in single-threaded context only
const cache = createCache();
适用于单行或小范围上下文：
javascript
// @ai-pattern: Singleton
// @ai-thread-safety: Not thread-safe, use in single-threaded context only
const cache = createCache();

Block Annotations

块级注释

For complex context:
python
"""
@ai-pattern: Factory Pattern
@ai-creational-pattern: true
@ai-rationale:
  Factory pattern used here because:
  1. Need to support multiple database backends (PostgreSQL, MySQL, SQLite)
  2. Configuration determines which implementation to instantiate
  3. Allows easy addition of new backends without modifying client code

@ai-extensibility:
  To add new database backend:
  1. Implement DatabaseBackend interface
  2. Register in BACKEND_REGISTRY dict
  3. Add configuration mapping in config/database.yaml

Example usage in docs/database-backends.md
"""
class DatabaseFactory:
    # Implementation
适用于复杂上下文：
python
"""
@ai-pattern: Factory Pattern
@ai-creational-pattern: true
@ai-rationale:
  Factory pattern used here because:
  1. Need to support multiple database backends (PostgreSQL, MySQL, SQLite)
  2. Configuration determines which implementation to instantiate
  3. Allows easy addition of new backends without modifying client code

@ai-extensibility:
  To add new database backend:
  1. Implement DatabaseBackend interface
  2. Register in BACKEND_REGISTRY dict
  3. Add configuration mapping in config/database.yaml

Example usage in docs/database-backends.md
"""
class DatabaseFactory:
    // Implementation

Structured Metadata

结构化元数据

typescript
/**
 * @ai-metadata {
 *   "pattern": "Observer",
 *   "subscribers": ["LoggingService", "MetricsService", "AuditService"],
 *   "event-types": ["user.created", "user.updated", "user.deleted"],
 *   "async": true,
 *   "guaranteed-delivery": false
 * }
 *
 * Event bus using observer pattern for loose coupling between services.
 * Events are published async with fire-and-forget semantics (no delivery guarantee).
 * For critical events requiring guaranteed delivery, use MessageQueue instead.
 */
class EventBus {
  // Implementation
}
typescript
/**
 * @ai-metadata {
 *   "pattern": "Observer",
 *   "subscribers": ["LoggingService", "MetricsService", "AuditService"],
 *   "event-types": ["user.created", "user.updated", "user.deleted"],
 *   "async": true,
 *   "guaranteed-delivery": false
 * }
 *
 * Event bus using observer pattern for loose coupling between services.
 * Events are published async with fire-and-forget semantics (no delivery guarantee).
 * For critical events requiring guaranteed delivery, use MessageQueue instead.
 */
class EventBus {
  // Implementation
}

Language-Specific Patterns

特定语言模式

TypeScript/JavaScript

TypeScript/JavaScript

typescript
/**
 * @ai-hook-usage
 * @react-hooks: [useState, useEffect, useCallback, useMemo]
 * @dependencies: {useCallback: [data, filter], useMemo: [data], useEffect: [id]}
 * @optimization: useMemo prevents expensive recalculation on re-renders
 *
 * This component uses React hooks for state and side effects. Dependency arrays
 * are carefully managed to prevent unnecessary re-renders and infinite loops.
 *
 * @ai-performance-note:
 * - useMemo caches filtered results (reduces filtering from O(n) per render to once per data change)
 * - useCallback memoizes event handlers (prevents child re-renders)
 */
export function DataTable({ data, id }: Props) {
  const [filter, setFilter] = useState('');

  const handleFilter = useCallback((value: string) => {
    setFilter(value);
  }, [data, filter]); // @ai-dependency-note: Both needed for closure

  const filteredData = useMemo(() => {
    return data.filter(item => item.name.includes(filter));
  }, [data]); // @ai-optimization: Only recompute when data changes

  // Implementation...
}
typescript
/**
 * @ai-hook-usage
 * @react-hooks: [useState, useEffect, useCallback, useMemo]
 * @dependencies: {useCallback: [data, filter], useMemo: [data], useEffect: [id]}
 * @optimization: useMemo prevents expensive recalculation on re-renders
 *
 * This component uses React hooks for state and side effects. Dependency arrays
 * are carefully managed to prevent unnecessary re-renders and infinite loops.
 *
 * @ai-performance-note:
 * - useMemo caches filtered results (reduces filtering from O(n) per render to once per data change)
 * - useCallback memoizes event handlers (prevents child re-renders)
 */
export function DataTable({ data, id }: Props) {
  const [filter, setFilter] = useState('');

  const handleFilter = useCallback((value: string) => {
    setFilter(value);
  }, [data, filter]); // @ai-dependency-note: Both needed for closure

  const filteredData = useMemo(() => {
    return data.filter(item => item.name.includes(filter));
  }, [data]); // @ai-optimization: Only recompute when data changes

  // Implementation...
}

Python

Python

python
undefined
python
undefined

@ai-decorator-stack

@ai-decorator-stack

@decorators: [retry, cache, log_execution, validate_auth]

@decorators: [retry, cache, log_execution, validate_auth]

@execution-order: validate_auth -> log_execution -> cache -> retry -> function

@execution-order: validate_auth -> log_execution -> cache -> retry -> function

Decorator execution order matters:

Decorator execution order matters:

1. validate_auth: Must run first to prevent unauthorized cache hits

1. validate_auth: Must run first to prevent unauthorized cache hits

2. log_execution: Log after auth but before cache to track all attempts

2. log_execution: Log after auth but before cache to track all attempts

3. cache: After logging to avoid logging cache hits

3. cache: After logging to avoid logging cache hits

4. retry: Innermost to retry actual function, not auth/logging

4. retry: Innermost to retry actual function, not auth/logging

@validate_auth(roles=["admin", "operator"]) @log_execution(level="INFO") @cache(ttl=300, key_func=lambda args: f"user:{args[0]}") @retry(max_attempts=3, backoff=exponential) def get_user_profile(user_id: int) -> UserProfile: """ @ai-caching-strategy: Time-based (TTL=300s) @ai-invalidation: Manual invalidation on user.updated event @ai-cache-key: user:{user_id} """ # Implementation
undefined
@validate_auth(roles=["admin", "operator"]) @log_execution(level="INFO") @cache(ttl=300, key_func=lambda args: f"user:{args[0]}") @retry(max_attempts=3, backoff=exponential) def get_user_profile(user_id: int) -> UserProfile: """ @ai-caching-strategy: Time-based (TTL=300s) @ai-invalidation: Manual invalidation on user.updated event @ai-cache-key: user:{user_id} """ // Implementation
undefined

Go

Go

go
// @ai-concurrency
// @pattern: Worker Pool
// @workers: 10 (configurable via WORKER_POOL_SIZE)
// @channel-buffer: 100
// @backpressure-handling: Blocks when buffer full
//
// This implements a worker pool pattern for concurrent processing.
// Workers are started at server initialization and kept alive for
// the server lifetime (no dynamic scaling).
//
// @ai-monitoring:
//   - Metric: worker_pool_queue_depth (current channel buffer size)
//   - Metric: worker_pool_processing_time (histogram)
//   - Alert: Queue depth > 80 for >5min (add workers)

type WorkerPool struct {
    workers   int
    jobQueue  chan Job
    resultCh  chan Result
    // fields...
}
go
// @ai-concurrency
// @pattern: Worker Pool
// @workers: 10 (configurable via WORKER_POOL_SIZE)
// @channel-buffer: 100
// @backpressure-handling: Blocks when buffer full
//
// This implements a worker pool pattern for concurrent processing.
// Workers are started at server initialization and kept alive for
// the server lifetime (no dynamic scaling).
//
// @ai-monitoring:
//   - Metric: worker_pool_queue_depth (current channel buffer size)
//   - Metric: worker_pool_processing_time (histogram)
//   - Alert: Queue depth > 80 for >5min (add workers)

type WorkerPool struct {
    workers   int
    jobQueue  chan Job
    resultCh  chan Result
    // fields...
}

Rust

Rust

rust
/// @ai-lifetime-annotations
/// @lifetimes: ['a, 'b]
/// @invariants:
///   - 'a must outlive 'b (parser must live longer than input)
///   - Output references bound to 'a (safe as long as input lives)
///
/// Lifetime relationships:
/// - Parser<'a> borrows input for 'a
/// - Output<'a> contains references to input (bounded by 'a)
/// - Temporary allocations use 'b (scoped to parsing only)
///
/// @ai-safety:
/// These lifetime constraints prevent dangling references by ensuring
/// the input buffer outlives all references derived from it.

pub struct Parser<'a> {
    input: &'a str,
    // fields...
}
rust
/// @ai-lifetime-annotations
/// @lifetimes: ['a, 'b]
/// @invariants:
///   - 'a must outlive 'b (parser must live longer than input)
///   - Output references bound to 'a (safe as long as input lives)
///
/// Lifetime relationships:
/// - Parser<'a> borrows input for 'a
/// - Output<'a> contains references to input (bounded by 'a)
/// - Temporary allocations use 'b (scoped to parsing only)
///
/// @ai-safety:
/// These lifetime constraints prevent dangling references by ensuring
/// the input buffer outlives all references derived from it.

pub struct Parser<'a> {
    input: &'a str,
    // fields...
}

Integration with Tools

与工具的集成

IDE Integration

IDE集成

Annotations can be extracted by IDE plugins:
bash
undefined
注释可由IDE插件提取：
bash
undefined

Extract all AI annotations

Extract all AI annotations

rg "@ai-\w+" --type ts --json | jq '.text'
rg "@ai-\w+" --type ts --json | jq '.text'

Find security-related annotations

Find security-related annotations

rg "@ai-security" -A 10
rg "@ai-security" -A 10

Find performance bottlenecks

Find performance bottlenecks

rg "@bottleneck: true" --type java
undefined
rg "@bottleneck: true" --type java
undefined

Static Analysis

静态分析

Custom linters can enforce annotation standards:
javascript
// Example: ESLint rule to enforce @ai-security on auth functions
module.exports = {
  rules: {
    'require-security-annotation': {
      create(context) {
        return {
          FunctionDeclaration(node) {
            if (node.id.name.includes('auth') || node.id.name.includes('Auth')) {
              // Check for @ai-security annotation
            }
          }
        };
      }
    }
  }
};
自定义检查器可强制执行注释标准：
javascript
// Example: ESLint rule to enforce @ai-security on auth functions
module.exports = {
  rules: {
    'require-security-annotation': {
      create(context) {
        return {
          FunctionDeclaration(node) {
            if (node.id.name.includes('auth') || node.id.name.includes('Auth')) {
              // Check for @ai-security annotation
            }
          }
        };
      }
    }
  }
};

Documentation Generation

文档生成

Extract annotations to generate documentation:
python
undefined
提取注释以生成文档：
python
undefined

doc_generator.py

doc_generator.py

import re from pathlib import Path
def extract_ai_annotations(file_path): """Extract all @ai-* annotations from file""" with open(file_path) as f: content = f.read()
pattern = r'@ai-(\w+):\s*(.+)'
return re.findall(pattern, content)
import re from pathlib import Path
def extract_ai_annotations(file_path): """Extract all @ai-* annotations from file""" with open(file_path) as f: content = f.read()
pattern = r'@ai-(\w+):\s*(.+)'
return re.findall(pattern, content)

Generate markdown documentation from annotations

Generate markdown documentation from annotations

undefined
undefined

Annotation Best Practices

注释最佳实践

Consistency

一致性

Use consistent annotation formats across codebase:
typescript
// ✅ GOOD - Consistent format
// @ai-pattern: Strategy
// @ai-alternatives: [Template Method, State Pattern]

// @ai-pattern: Observer
// @ai-alternatives: [Event Emitter, Pub/Sub]

// ❌ BAD - Inconsistent format
// @ai-pattern: Strategy (alternatives: Template Method, State)
// Pattern: Observer | Alternatives: Event Emitter, Pub/Sub
在整个代码库中使用一致的注释格式：
typescript
// ✅ 良好 - 格式一致
// @ai-pattern: Strategy
// @ai-alternatives: [Template Method, State Pattern]

// @ai-pattern: Observer
// @ai-alternatives: [Event Emitter, Pub/Sub]

// ❌ 糟糕 - 格式不一致
// @ai-pattern: Strategy (alternatives: Template Method, State)
// Pattern: Observer | Alternatives: Event Emitter, Pub/Sub

Completeness

完整性

Include all relevant metadata:
python
undefined
包含所有相关元数据：
python
undefined

✅ GOOD - Complete context

✅ 良好 - 上下文完整

@ai-security

@ai-security

@risk-level: High

@risk-level: High

@cwe: CWE-79 (XSS)

@cwe: CWE-79 (XSS)

@input-sanitization: HTML encoding applied

@input-sanitization: HTML encoding applied

@output-encoding: UTF-8

@output-encoding: UTF-8

@tested: XSS test suite in tests/security/xss_test.py

@tested: XSS test suite in tests/security/xss_test.py

❌ BAD - Incomplete

❌ 糟糕 - 内容不完整

@ai-security

@ai-security

Security risk here

Security risk here

undefined
undefined

Maintainability

可维护性

Keep annotations up-to-date:
go
// ✅ GOOD - Dated and tracked
// @ai-tech-debt
// @added: 2025-12-04
// @reviewed: 2025-12-04
// @next-review: 2026-01-04

// ❌ BAD - Stale and outdated
// @ai-tech-debt
// TODO: Fix this eventually
保持注释更新：
go
// ✅ 良好 - 有日期和跟踪
// @ai-tech-debt
// @added: 2025-12-04
// @reviewed: 2025-12-04
// @next-review: 2026-01-04

// ❌ 糟糕 - 陈旧过时
// @ai-tech-debt
// TODO: Fix this eventually

Anti-Patterns

反模式

Don't

请勿

❌ Over-annotate obvious code
javascript
// @ai-pattern: Variable Declaration
const user = getUser(); // Bad - obvious
❌ Use annotations instead of fixing code
python
undefined
❌ 对明显代码过度注释
javascript
// @ai-pattern: Variable Declaration
const user = getUser(); // 糟糕 - 显而易见
❌ 用注释代替修复代码
python
undefined

@ai-tech-debt: This is terrible code

@ai-tech-debt: This is terrible code

@ai-security: Has vulnerabilities

@ai-security: Has vulnerabilities

@ai-performance: Slow

@ai-performance: Slow

Bad - just fix the code!

糟糕 - 直接修复代码即可！


❌ Inconsistent tag naming

```typescript
// @AI-PATTERN vs @ai-pattern vs @aiPattern
// Use consistent naming

❌ 标签命名不一致

```typescript
// @AI-PATTERN vs @ai-pattern vs @aiPattern
// 使用一致的命名

Do

建议

✅ Annotate complex or non-obvious patterns
rust
/// @ai-pattern: Typestate
/// @ai-compile-time-safety: true
///
/// Uses typestate pattern to enforce protocol state machine at compile time.
/// Impossible states are unrepresentable in type system.
✅ Provide actionable information
java
/**
 * @ai-tech-debt
 * @action: Extract UserValidator class
 * @files-affected: [UserService.java, UserController.java, UserTest.java]
 * @effort: 3-4 hours
 * @priority: Medium
 */
✅ Link to external resources
python
undefined
✅ 对复杂或非显而易见的模式进行注释
rust
/// @ai-pattern: Typestate
/// @ai-compile-time-safety: true
///
/// 使用类型状态模式在编译时强制协议状态机。
/// 不可能的状态在类型系统中无法表示。
✅ 提供可操作的信息
java
/**
 * @ai-tech-debt
 * @action: 提取UserValidator类
 * @files-affected: [UserService.java, UserController.java, UserTest.java]
 * @effort: 3-4小时
 * @priority: 中等
 */
✅ 链接到外部资源
python
undefined

@ai-algorithm: Dijkstra's shortest path

@ai-algorithm: Dijkstra's shortest path

@reference: https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm

@reference: https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm

@paper: "A Note on Two Problems in Connexion with Graphs" (1959)

@paper: "A Note on Two Problems in Connexion with Graphs" (1959)

@optimization: Using binary heap for O((V+E) log V) complexity

@optimization: 使用二叉堆实现O((V+E) log V)复杂度

undefined
undefined

Related Skills

相关技能

  • notetaker-fundamentals
  • documentation-linking
  • notetaker-fundamentals
  • documentation-linking

Resources

资源