---
name: comment-code
description: Bilingual code comments in Vietnamese and English. Use for documenting functions, classes, or adding EN/VI documentation.
metadata:
  author: Velik Ho
  version: "1.0"
---

# Bilingual Code Comments / Chú Thích Code Song Ngữ

Add comprehensive code comments in both Vietnamese and English to improve code readability for international and Vietnamese teams.

## When to Use This Skill / Khi Nào Sử Dụng

Use this skill when:
- Adding comments to new code / Thêm chú thích cho code mới
- Documenting existing code / Viết tài liệu cho code hiện có
- Creating JSDoc/TSDoc documentation / Tạo JSDoc/TSDoc
- Writing function/class descriptions / Viết mô tả hàm/lớp
- Explaining complex logic / Giải thích logic phức tạp
- Adding inline comments / Thêm chú thích inline

## Core Concepts / Khái Niệm Cốt Lõi

### Comment Format Rules / Quy Tắc Định Dạng

1. **EN first, then VI**: Always put English before Vietnamese
2. **Keep together**: Place bilingual comments on adjacent lines
3. **Near code**: Comments should be close to what they describe
4. **JSDoc for exports**: Use JSDoc format for public APIs

### Documentation Priority / Độ Ưu Tiên

| Priority | What to Document |
|----------|------------------|
| **High** | Public APIs, complex algorithms, security-critical code |
| **Medium** | Helper functions, data transformations, integrations |
| **Low** | Simple getters/setters, self-explanatory code |

## Key Patterns / Mẫu Chính

### Single-line Comments / Chú Thích Một Dòng

```typescript
// EN: Initialize database connection
// VI: Khởi tạo kết nối database
const db = await createConnection();
```

### Function Documentation / Tài Liệu Hàm

```typescript
/**
 * EN: Calculates the total price including tax and discount
 * VI: Tính tổng giá bao gồm thuế và giảm giá
 * 
 * @param basePrice - Original price / Giá gốc
 * @param taxRate - Tax rate (0-1) / Tỷ lệ thuế (0-1)
 * @param discount - Discount amount / Số tiền giảm giá
 * @returns Final price / Giá cuối cùng
 */
function calculateTotal(
  basePrice: number,
  taxRate: number,
  discount: number
): number {
  // EN: Apply discount first
  // VI: Áp dụng giảm giá trước
  const discountedPrice = basePrice - discount;
  
  // EN: Then calculate tax
  // VI: Sau đó tính thuế
  return discountedPrice * (1 + taxRate);
}
```

### Class Documentation / Tài Liệu Lớp

```typescript
/**
 * EN: Handles user authentication and authorization
 * VI: Xử lý xác thực và phân quyền người dùng
 */
export class AuthService {
  /**
   * EN: JWT secret key from environment
   * VI: Khóa bí mật JWT từ biến môi trường
   */
  private readonly jwtSecret: string;

  /**
   * EN: Verify JWT token and return user payload
   * VI: Xác minh JWT token và trả về thông tin người dùng
   * 
   * @param token - JWT token to verify / JWT token cần xác minh
   * @returns User payload / Thông tin người dùng
   * @throws TokenExpiredError if token expired / Lỗi token hết hạn
   */
  async verifyToken(token: string): Promise<UserPayload> {
    // Implementation
  }
}
```

### Interface/Type Documentation / Tài Liệu Interface/Type

```typescript
/**
 * EN: User data transfer object
 * VI: Đối tượng truyền dữ liệu người dùng
 */
interface UserDto {
  /** EN: Unique user identifier / VI: Mã định danh duy nhất */
  id: string;
  
  /** EN: User email address / VI: Địa chỉ email người dùng */
  email: string;
  
  /** EN: User role for authorization / VI: Vai trò để phân quyền */
  role: 'admin' | 'user' | 'guest';
}
```

### React Components

```typescript
/**
 * EN: User profile card component
 * VI: Component thẻ hồ sơ người dùng
 * 
 * @param user - User data to display / Dữ liệu người dùng
 * @param onEdit - Callback when edit clicked / Callback khi nhấn chỉnh sửa
 */
export function UserCard({ user, onEdit }: UserCardProps) {
  // EN: Local state for loading status
  // VI: State cục bộ cho trạng thái loading
  const [isLoading, setIsLoading] = useState(false);

  return (
    <div className="user-card">
      {/* EN: Display user avatar / VI: Hiển thị avatar */}
      <img src={user.avatar} alt={user.name} />
    </div>
  );
}
```

### Prisma Schema

```prisma
/// EN: User model for authentication and profile
/// VI: Model người dùng cho xác thực và hồ sơ
model User {
  /// EN: Unique identifier / VI: Mã định danh duy nhất
  id        String   @id @default(cuid())
  
  /// EN: User email (unique) / VI: Email người dùng (duy nhất)
  email     String   @unique
  
  /// EN: Account creation timestamp / VI: Thời gian tạo tài khoản
  createdAt DateTime @default(now())

  @@map("users")
}
```

### Special Comments / Chú Thích Đặc Biệt

```typescript
// TODO EN: Implement caching for better performance
// TODO VI: Triển khai caching để cải thiện hiệu suất

// FIXME EN: This causes memory leak, needs refactoring
// FIXME VI: Đoạn này gây rò rỉ bộ nhớ, cần refactor

// WARNING EN: Do not modify without updating database schema
// WARNING VI: Không sửa đổi mà không cập nhật schema database
```

## Common Mistakes / Lỗi Thường Gặp

### 1. Stating the Obvious / Nói Điều Hiển Nhiên

```typescript
// ❌ BAD: States the obvious
// EN: Set x to 5
// VI: Gán x bằng 5
const x = 5;

// ✅ GOOD: Explains why
// EN: Default timeout in seconds for API calls
// VI: Timeout mặc định (giây) cho các API call
const x = 5;
```

### 2. Missing Translation / Thiếu Bản Dịch

```typescript
// ❌ BAD: Missing Vietnamese
// EN: Calculate discount
const discount = price * 0.1;

// ✅ GOOD: Both languages
// EN: Calculate 10% discount for members
// VI: Tính giảm giá 10% cho thành viên
const discount = price * 0.1;
```

### 3. Outdated Comments / Chú Thích Lỗi Thời

```typescript
// ❌ BAD: Comment says email, code uses phone
// EN: Validate email format
// VI: Xác thực định dạng email
validatePhone(phone);

// ✅ GOOD: Keep comments in sync with code
// EN: Validate phone number format
// VI: Xác thực định dạng số điện thoại
validatePhone(phone);
```

### 4. No JSDoc for Public APIs

```typescript
// ❌ BAD: Exported function without JSDoc
export function processOrder(order: Order) { ... }

// ✅ GOOD: Full JSDoc for exported functions
/**
 * EN: Process order and update inventory
 * VI: Xử lý đơn hàng và cập nhật kho
 * @param order - Order to process / Đơn hàng cần xử lý
 * @returns ProcessingResult / Kết quả xử lý
 */
export function processOrder(order: Order): ProcessingResult { ... }
```

## Quick Reference / Tham Chiếu Nhanh

### Function Comment Template

```typescript
/**
 * EN: [Brief description in English]
 * VI: [Mô tả ngắn gọn bằng tiếng Việt]
 * 
 * @param paramName - EN description / VI mô tả
 * @returns EN description / VI mô tả
 * @throws ErrorType EN when / VI khi nào
 */
```

### Inline Comment Template

```typescript
// EN: [English explanation]
// VI: [Giải thích tiếng Việt]
```

### JSX Comment Template

```tsx
{/* EN: [Description] / VI: [Mô tả] */}
```

### Comment Prefixes

| Prefix | Usage |
|--------|-------|
| `// EN:` + `// VI:` | Standard bilingual inline |
| `/** */` | JSDoc for functions/classes |
| `///` | Prisma schema comments |
| `{/* */}` | JSX/TSX comments |
| `// TODO` | Future improvements |
| `// FIXME` | Known issues to fix |
| `// WARNING` | Critical cautions |

## Resources / Tài Nguyên

- [Project Rules](../project-rules/SKILL.md) - Code organization standards
- [Documentation](../documentation/SKILL.md) - Documentation patterns
- [API Design](../api-design/SKILL.md) - API documentation standards
- [Skill Authoring](../skill-authoring/SKILL.md) - How to write skills