285 lines
7.8 KiB
Markdown
285 lines
7.8 KiB
Markdown
---
|
|
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
|