Cách Viết Code Comment Bằng Tiếng Anh — Dễ Hiểu, Chuyên Nghiệp

1
2
3
4
5
6

// ❌ Bad — comment thừa
// Check if user is active
if (user.isActive) { ... }

// ✅ Good — code tự rõ, không cần comment
if (user.isActive) { ... }

1
2
3
4
5
6
7

# ❌ Bad — diễn tả lại code
# Increment counter by 1
counter += 1

# ✅ Good — giải thích WHY
# Reset attempt counter after successful login to prevent lockout carry-over
counter = 0

1
2

const MAX_RETRIES = 3; // Limit retries to prevent infinite loops
const timeout = 5000;  // Milliseconds — matches API gateway timeout

1
2
3
4
5
6

/*
 * Calculate the shipping cost based on weight and destination zone.
 * Uses tiered pricing: first 5kg at base rate, additional weight at
 * reduced rate. International zones add a 15% surcharge.
 */
public double calculateShippingCost(double weight, int zone) { ... }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

/**
 * Send a password reset email to the user.
 *
 * @param email - The user's registered email address
 * @param locale - Language code for the email template (default: "en")
 * @returns A promise that resolves to true if the email was sent successfully
 * @throws {UserNotFoundError} If no account matches the email
 *
 * @example
 * await sendPasswordReset("[email protected]", "vi");
 */
async function sendPasswordReset(email: string, locale?: string): Promise<boolean> { ... }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

def calculate_discount(price: float, tier: str) -> float:
    """Calculate the discount amount based on the customer's membership tier.

    Uses a tiered discount system:
    - Silver: 5%
    - Gold: 10%
    - Platinum: 15%

    Args:
        price: The original price before discount.
        tier: The customer's membership tier ("silver", "gold", or "platinum").

    Returns:
        The discount amount in the same currency as the input price.

    Raises:
        ValueError: If the tier is not recognized.
    """

1
2
3
4
5

// TODO: Migrate to WebSocket for real-time updates (tracking: JIRA-1234)
// FIXME: Race condition when two users submit at the same time
// HACK: Workaround for Chrome 120 flexbox rendering bug
// NOTE: This endpoint is deprecated — use /v2/users instead
// WARNING: Do not change the order of these operations — it will break idempotency

1
2
3
4
5

// We use X because Y
// This is necessary because ...
// Required by [spec/regulation/API contract]
// Intentionally left blank — handled by the parent component
// Chosen over X for better performance in high-traffic scenarios

1
2
3
4

// WARNING: Changing this will break backward compatibility
// IMPORTANT: This must run before database migration
// Do NOT remove — required for legacy client support
// Order matters here — see incident report #452

1
2
3
4

// TODO(author): Brief description (ticket: PROJ-123)
// FIXME: Describe the bug — fails when input > 10MB
// HACK: Temporary fix until upstream library patches issue #789
// DEPRECATED: Use calculateTaxV2() instead — will be removed in v3.0

1
2
3
4

// Algorithm: Two-pointer approach — O(n) time, O(1) space
// Step 1: Sort the array in ascending order
// Step 2: Use binary search to find the target
// We iterate backwards to preserve insertion order

1
2
3
4
5
6
7

# Bad
# Set x to 5
x = 5

# Loop through the list
for item in items:
    process(item)

1
2

// Kiểm tra xem user có active không
// → Đồng nghiệp nước ngoài không đọc được!

1
2
3
4
5

// Returns the user's full name
// → Nhưng function đã đổi sang return nickname 3 tháng trước!
public String getDisplayName() {
    return user.getNickname(); // Comment nói "full name" nhưng code trả về nickname
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// ❌ Too much
// This function is used to validate the email address that the user
// enters into the registration form on the signup page. It checks
// whether the email contains an @ symbol and a valid domain name
// using a regular expression pattern.
function validateEmail(email) { ... }

// ✅ Just right
// Validate email format using RFC 5322 simplified regex
function validateEmail(email) { ... }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// 1. Comment thừa
// Add 1 to count
count++;

// 2. Comment tiếng Việt
// Lấy danh sách user từ database
const users = await db.query("SELECT * FROM users");

// 3. Comment mơ hồ
// Fix the thing
if (data.length === 0) return [];

1
2
3
4
5
6
7
8

def retry(func, max_attempts=3, delay=1):
    for attempt in range(max_attempts):
        try:
            return func()
        except Exception:
            if attempt == max_attempts - 1:
                raise
            time.sleep(delay * (2 ** attempt))

1
2
3
4
5

// Kiểm tra xem token có hết hạn chưa, nếu hết hạn thì refresh
// Cần refresh trước 5 phút để tránh bị lỗi giữa chừng
if (token.expiresAt < now + 300) {
    token = refreshToken(token);
}