chore: Remove obsolete skill documentation files
- Deleted multiple outdated skill documentation files, including those related to API design, API gateway patterns, versioning strategies, caching patterns, CI/CD advanced patterns, bilingual code comments, configuration management, data consistency patterns, Prisma database patterns, Kubernetes deployment patterns, and more. - This cleanup streamlines the documentation repository, ensuring that only relevant and up-to-date information is maintained for current development practices.
This commit is contained in:
Ho Ngoc Hai
@@ -1,489 +0,0 @@
|
||||
---
|
||||
name: comment-code
|
||||
description: Add bilingual code comments in Vietnamese and English for better documentation. Use when adding comments to code, documenting functions/classes, or when user requests Vietnamese/English documentation.
|
||||
---
|
||||
|
||||
# Bilingual Code Comments
|
||||
|
||||
Add comprehensive code comments in both Vietnamese and English to improve code readability for international and Vietnamese teams.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Adding comments to new code
|
||||
- Documenting existing code
|
||||
- Creating JSDoc/TSDoc documentation
|
||||
- Writing function/class descriptions
|
||||
- Explaining complex logic
|
||||
- Adding inline comments
|
||||
|
||||
## Comment Structure
|
||||
|
||||
The following diagram illustrates the structure and hierarchy of comment types used in the GoodGo codebase:
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph CommentTypes["Comment Types"]
|
||||
SingleLine["Single-line Comments<br/>// EN: ...<br/>// VI: ..."]
|
||||
MultiLine["Multi-line Comments<br/>/* EN: ...<br/>VI: ... */"]
|
||||
JSDoc["JSDoc Comments<br/>/** EN: ...<br/>VI: ... */"]
|
||||
Prisma["Prisma Comments<br/>/// EN: ...<br/>VI: ..."]
|
||||
end
|
||||
|
||||
subgraph Contexts["Code Contexts"]
|
||||
Functions["Functions"]
|
||||
Classes["Classes"]
|
||||
Interfaces["Interfaces/Types"]
|
||||
Components["React Components"]
|
||||
Controllers["API Controllers"]
|
||||
Middleware["Middleware"]
|
||||
Schema["Prisma Schema"]
|
||||
Config["Configuration"]
|
||||
end
|
||||
|
||||
subgraph SpecialTypes["Special Comment Types"]
|
||||
TODO["TODO Comments"]
|
||||
FIXME["FIXME Comments"]
|
||||
WARNING["WARNING Comments"]
|
||||
NOTE["NOTE Comments"]
|
||||
end
|
||||
|
||||
subgraph Format["Bilingual Format"]
|
||||
EN["English (EN)<br/>First"]
|
||||
VI["Vietnamese (VI)<br/>Second"]
|
||||
end
|
||||
|
||||
JSDoc --> Functions
|
||||
JSDoc --> Classes
|
||||
JSDoc --> Interfaces
|
||||
JSDoc --> Components
|
||||
JSDoc --> Controllers
|
||||
JSDoc --> Middleware
|
||||
|
||||
SingleLine --> Config
|
||||
SingleLine --> SpecialTypes
|
||||
|
||||
MultiLine --> Functions
|
||||
MultiLine --> Classes
|
||||
|
||||
Prisma --> Schema
|
||||
|
||||
Format --> CommentTypes
|
||||
Format --> Contexts
|
||||
Format --> SpecialTypes
|
||||
|
||||
style CommentTypes fill:#e1f5ff
|
||||
style Contexts fill:#fff4e1
|
||||
style SpecialTypes fill:#ffe1f5
|
||||
style Format fill:#e1ffe1
|
||||
```
|
||||
|
||||
## Documentation Flow
|
||||
|
||||
The following diagram shows the decision flow for adding comments to code:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([Start: Writing Code]) --> CheckType{What type of<br/>code element?}
|
||||
|
||||
CheckType -->|Public API| HighPriority[High Priority:<br/>Always Document]
|
||||
CheckType -->|Complex Logic| HighPriority
|
||||
CheckType -->|Security Code| HighPriority
|
||||
CheckType -->|Config/Setup| HighPriority
|
||||
CheckType -->|Error Handling| HighPriority
|
||||
|
||||
CheckType -->|Helper Function| MediumPriority[Medium Priority:<br/>Document if Helpful]
|
||||
CheckType -->|Data Transform| MediumPriority
|
||||
CheckType -->|External Integration| MediumPriority
|
||||
|
||||
CheckType -->|Simple Getter/Setter| LowPriority[Low Priority:<br/>Optional]
|
||||
CheckType -->|Self-explanatory| LowPriority
|
||||
CheckType -->|Standard CRUD| LowPriority
|
||||
|
||||
HighPriority --> ChooseFormat{Choose Comment<br/>Format}
|
||||
MediumPriority --> ChooseFormat
|
||||
LowPriority --> ChooseFormat
|
||||
|
||||
ChooseFormat -->|Function/Class| UseJSDoc[Use JSDoc Format<br/>/** EN: ...<br/>VI: ... */]
|
||||
ChooseFormat -->|Brief Explanation| UseSingleLine[Use Single-line<br/>// EN: ...<br/>// VI: ...]
|
||||
ChooseFormat -->|Multi-step Process| UseMultiLine[Use Multi-line<br/>/* EN: ...<br/>VI: ... */]
|
||||
ChooseFormat -->|Prisma Schema| UsePrisma[Use Prisma Format<br/>/// EN: ...<br/>VI: ...]
|
||||
|
||||
UseJSDoc --> AddParams[Add @param tags<br/>Add @returns tag<br/>Add @throws if needed]
|
||||
UseSingleLine --> WriteBilingual[Write Bilingual:<br/>EN first, VI second]
|
||||
UseMultiLine --> WriteBilingual
|
||||
UsePrisma --> WriteBilingual
|
||||
|
||||
AddParams --> WriteBilingual
|
||||
WriteBilingual --> CheckSpecial{Special<br/>Comment Type?}
|
||||
|
||||
CheckSpecial -->|Future Work| AddTODO[Add TODO prefix]
|
||||
CheckSpecial -->|Needs Fix| AddFIXME[Add FIXME prefix]
|
||||
CheckSpecial -->|Important Warning| AddWARNING[Add WARNING prefix]
|
||||
CheckSpecial -->|Important Note| AddNOTE[Add NOTE prefix]
|
||||
CheckSpecial -->|No| End([Done])
|
||||
|
||||
AddTODO --> End
|
||||
AddFIXME --> End
|
||||
AddWARNING --> End
|
||||
AddNOTE --> End
|
||||
|
||||
style HighPriority fill:#ffcccc
|
||||
style MediumPriority fill:#ffffcc
|
||||
style LowPriority fill:#ccffcc
|
||||
style UseJSDoc fill:#cce5ff
|
||||
style UseSingleLine fill:#cce5ff
|
||||
style UseMultiLine fill:#cce5ff
|
||||
style UsePrisma fill:#cce5ff
|
||||
```
|
||||
|
||||
## Comment Format
|
||||
|
||||
### Single-line Comments
|
||||
|
||||
```typescript
|
||||
// EN: Initialize database connection
|
||||
// VI: Khởi tạo kết nối database
|
||||
const db = await createConnection();
|
||||
```
|
||||
|
||||
### Multi-line Comments
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* EN: Validates user credentials and returns JWT token
|
||||
* VI: Xác thực thông tin đăng nhập và trả về JWT token
|
||||
*
|
||||
* @param email - User email address / Địa chỉ email người dùng
|
||||
* @param password - User password / Mật khẩu người dùng
|
||||
* @returns JWT token / Mã JWT token
|
||||
* @throws AuthenticationError if credentials invalid / Lỗi xác thực nếu thông tin không hợp lệ
|
||||
*/
|
||||
async function login(email: string, password: string): Promise<string> {
|
||||
// Implementation
|
||||
}
|
||||
```
|
||||
|
||||
## Core Comment Patterns
|
||||
|
||||
### Function Documentation
|
||||
```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ế
|
||||
const tax = discountedPrice * taxRate;
|
||||
|
||||
return discountedPrice + tax;
|
||||
}
|
||||
```
|
||||
|
||||
### Class Documentation
|
||||
```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
|
||||
```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 display name / VI: Tên hiển thị người dùng */
|
||||
name: string;
|
||||
|
||||
/** EN: User role for authorization / VI: Vai trò người dùng để 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 để hiển thị
|
||||
* @param onEdit - Callback when edit button clicked / Callback khi nhấn nút 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 người dùng */}
|
||||
<img src={user.avatar} alt={user.name} />
|
||||
|
||||
{/* EN: User information section / VI: Phần thông tin người dùng */}
|
||||
<div className="user-info">
|
||||
<h3>{user.name}</h3>
|
||||
<p>{user.email}</p>
|
||||
</div>
|
||||
</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: Hashed password / VI: Mật khẩu đã mã hóa
|
||||
password String
|
||||
|
||||
/// EN: Display name / VI: Tên hiển thị
|
||||
name String
|
||||
|
||||
/// EN: Account creation timestamp / VI: Thời gian tạo tài khoản
|
||||
createdAt DateTime @default(now())
|
||||
|
||||
/// EN: Last update timestamp / VI: Thời gian cập nhật cuối
|
||||
updatedAt DateTime @updatedAt
|
||||
|
||||
@@map("users")
|
||||
}
|
||||
```
|
||||
|
||||
### API Controllers
|
||||
```typescript
|
||||
/**
|
||||
* EN: User management controller
|
||||
* VI: Controller quản lý người dùng
|
||||
*/
|
||||
export class UserController {
|
||||
/**
|
||||
* EN: Get user by ID
|
||||
* VI: Lấy thông tin người dùng theo ID
|
||||
*
|
||||
* GET /api/users/:id
|
||||
*/
|
||||
async getById(req: Request, res: Response) {
|
||||
try {
|
||||
// EN: Extract user ID from params
|
||||
// VI: Lấy ID người dùng từ params
|
||||
const { id } = req.params;
|
||||
|
||||
// EN: Fetch user from database
|
||||
// VI: Lấy người dùng từ database
|
||||
const user = await this.userService.findById(id);
|
||||
|
||||
if (!user) {
|
||||
return res.status(404).json({
|
||||
success: false,
|
||||
error: {
|
||||
code: 'USER_NOT_FOUND',
|
||||
message: 'User not found / Không tìm thấy người dùng',
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
return res.json({
|
||||
success: true,
|
||||
data: user,
|
||||
});
|
||||
} catch (error) {
|
||||
logger.error('Failed to get user', { error, userId: req.params.id });
|
||||
return res.status(500).json({
|
||||
success: false,
|
||||
error: {
|
||||
code: 'INTERNAL_ERROR',
|
||||
message: 'Internal server error / Lỗi máy chủ nội bộ',
|
||||
},
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Middleware
|
||||
```typescript
|
||||
/**
|
||||
* EN: Authentication middleware to verify JWT tokens
|
||||
* VI: Middleware xác thực để kiểm tra JWT token
|
||||
*/
|
||||
export function authMiddleware(
|
||||
req: Request,
|
||||
res: Response,
|
||||
next: NextFunction
|
||||
) {
|
||||
// EN: Extract token from Authorization header
|
||||
// VI: Lấy token từ header Authorization
|
||||
const authHeader = req.headers.authorization;
|
||||
const token = authHeader?.replace('Bearer ', '');
|
||||
|
||||
if (!token) {
|
||||
return res.status(401).json({
|
||||
success: false,
|
||||
error: {
|
||||
code: 'NO_TOKEN',
|
||||
message: 'Authentication required / Yêu cầu xác thực',
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
try {
|
||||
// EN: Verify token and extract payload
|
||||
// VI: Xác minh token và lấy payload
|
||||
const payload = jwt.verify(token, JWT_SECRET);
|
||||
req.user = payload;
|
||||
next();
|
||||
} catch (error) {
|
||||
return res.status(401).json({
|
||||
success: false,
|
||||
error: {
|
||||
code: 'INVALID_TOKEN',
|
||||
message: 'Invalid or expired token / Token không hợp lệ hoặc hết hạn',
|
||||
},
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Comment Placement
|
||||
- Place bilingual comments together (EN first, then VI)
|
||||
- Keep comments close to the code they describe
|
||||
- Use JSDoc format for functions and classes
|
||||
|
||||
### 2. Comment Content
|
||||
- **DO**: Explain WHY, not WHAT (code shows what)
|
||||
- **DO**: Document complex logic and business rules
|
||||
- **DO**: Include parameter descriptions and return types
|
||||
- **DO**: Document error conditions and exceptions
|
||||
- **DON'T**: State the obvious
|
||||
- **DON'T**: Write redundant comments
|
||||
|
||||
### 3. Language Guidelines
|
||||
- **English**: Use clear, concise technical English
|
||||
- **Vietnamese**: Use proper Vietnamese technical terms
|
||||
- Keep translations accurate and natural
|
||||
- Use consistent terminology across codebase
|
||||
|
||||
### 4. Special Cases
|
||||
|
||||
#### TODO Comments
|
||||
```typescript
|
||||
// TODO EN: Implement caching for better performance
|
||||
// TODO VI: Triển khai caching để cải thiện hiệu suất
|
||||
```
|
||||
|
||||
#### FIXME Comments
|
||||
```typescript
|
||||
// FIXME EN: This causes memory leak, needs refactoring
|
||||
// FIXME VI: Đoạn này gây rò rỉ bộ nhớ, cần refactor
|
||||
```
|
||||
|
||||
#### WARNING Comments
|
||||
```typescript
|
||||
// WARNING EN: Do not modify this without updating the database schema
|
||||
// WARNING VI: Không sửa đổi phần này mà không cập nhật schema database
|
||||
```
|
||||
|
||||
### 5. Documentation Priority
|
||||
|
||||
**High Priority** (Always document):
|
||||
- Public APIs and exported functions
|
||||
- Complex algorithms and business logic
|
||||
- Security-critical code
|
||||
- Configuration and environment setup
|
||||
- Error handling strategies
|
||||
|
||||
**Medium Priority** (Document when helpful):
|
||||
- Helper functions with non-obvious behavior
|
||||
- Data transformations
|
||||
- Integration points with external services
|
||||
|
||||
**Low Priority** (Optional):
|
||||
- Simple getters/setters
|
||||
- Self-explanatory code
|
||||
- Standard CRUD operations
|
||||
|
||||
|
||||
## Integration with Project Rules
|
||||
|
||||
When commenting code in this project:
|
||||
- Follow the code organization from `project-rules` skill
|
||||
- Use consistent terminology with project documentation
|
||||
- Align with the API response format standards
|
||||
- Document according to the testing standards
|
||||
- Include security considerations where relevant
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### 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]
|
||||
```
|
||||
|
||||
### Complex Block Template
|
||||
```typescript
|
||||
// EN: Step N: [What this block does]
|
||||
// VI: Bước N: [Block này làm gì]
|
||||
```
|
||||
Reference in New Issue
Block a user