pos-system/microservices/.agent/skills/comment-code/SKILL.md

name, description, metadata

name	description	metadata
comment-code	Bilingual code comments in Vietnamese and English. Use for documenting functions, classes, or adding EN/VI documentation.	author version Velik Ho 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

// 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

/**
 * 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

/**
 * 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

/**
 * 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

/**
 * 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

/// 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

// 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

// ❌ 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

// ❌ 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

// ❌ 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

// ❌ 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

/**
 * 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

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

JSX Comment Template

{/* 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 - Code organization standards
• Documentation - Documentation patterns
• API Design - API documentation standards
• Skill Authoring - How to write skills