Chú thích trong JavaScript: một dòng, khối và khi nào dùng

Hai loại chú thích

JavaScript có hai cú pháp chú thích (comment). Chú thích một dòng bắt đầu bằng // và kéo dài đến hết dòng:

// This is a single-line comment
let price = 100; // Comments can also trail code

console.log(price);

Chú thích khối bắt đầu bằng /* và kết thúc ở */ kế tiếp. Nó có thể trải dài bao nhiêu dòng tùy ý:

/*
  This is a block comment.
  It spans multiple lines.
  The interpreter ignores all of it.
*/

let total = 42;
console.log(total);

Cả hai dạng đều bị engine JavaScript bỏ qua hoàn toàn. Chúng tồn tại cho con người: cho bạn, cho đồng đội, và cho chính bạn sáu tháng sau khi đọc lại đoạn code này.

Chú thích một dòng

// là dạng bạn sẽ dùng nhiều nhất. Bất cứ thứ gì nằm sau // trên cùng một dòng đều là chú thích; dòng tiếp theo trở lại là code:

// Calculate the tax-inclusive price
const price = 100;
const taxRate = 0.08;
const total = price * (1 + taxRate); // final amount the customer pays

console.log(total);

Chú thích ở cuối dòng (sau một câu lệnh) ổn với ghi chú ngắn. Nếu ghi chú dài đến mức phải xuống dòng, hãy chuyển nó lên một dòng riêng phía trên đoạn code: chú thích cuối dòng quá dài sẽ bị trình soạn thảo cắt bớt và bị người đọc bỏ qua.

Chú thích khối

/* */ đáng dùng trong hai trường hợp: chú thích cần nhiều hơn một dòng, và chú thích nằm giữa một biểu thức.

/*
 * Applies a bulk discount when the order qualifies.
 * Rules change per quarter - see pricing spec #214.
 */
function bulkDiscount(quantity, unitPrice) {
    return quantity >= 10 ? unitPrice * 0.9 : unitPrice;
}

// Inline in the middle of an expression:
const area = /* width */ 10 * /* height */ 5;

console.log(bulkDiscount(12, 50));
console.log(area);

Một cái bẫy: chú thích khối không lồng nhau được. */ đầu tiên sẽ kết thúc chú thích, kể cả khi bạn tưởng mình vẫn đang ở trong một chú thích bên ngoài:

/* outer /* inner */ still outer */
// SyntaxError - the first */ closed the block,
// and "still outer */" is now invalid code.

Nếu cần vô hiệu hóa đoạn code đã chứa /* */, hãy dùng // cho từng dòng.

Vô hiệu hóa code bằng chú thích

Khi gỡ lỗi, bạn sẽ thường muốn tạm tắt vài dòng code. Cả hai dạng chú thích đều làm được:

function checkout(cart) {
    const subtotal = cart.reduce((sum, item) => sum + item.price, 0);

    // const shipping = calculateShipping(cart);
    // const total = subtotal + shipping;

    /*
    if (cart.length === 0) {
        throw new Error("Cart is empty");
    }
    */

    return subtotal;
}

console.log(checkout([{ price: 10 }, { price: 20 }]));

Trình soạn thảo nào cũng có phím tắt cho việc này: Ctrl+/ trên Windows/Linux, Cmd+/ trên Mac, để bật tắt // cho các dòng đang chọn. Học một lần, bạn sẽ dùng nó mỗi ngày.

Code bị vô hiệu hóa bằng chú thích chỉ nên là tạm thời. Đừng commit cả nghĩa địa code chết với dòng // old version, keep just in case phía trên. Hệ thống quản lý phiên bản đã nhớ code cũ giúp bạn rồi. Cứ xóa đi.

Chú thích vì sao, không chú thích cái gì

Đây là quy tắc duy nhất phân biệt chú thích có ích với chú thích gây nhiễu. Code đã cho thấy nó làm cái gì. Một chú thích tốt giải thích vì sao.

Chú thích gây nhiễu:

// Set x to 10
let x = 10;

// Loop through the array
for (let i = 0; i < x; i++) {
    // Add i to the total
    console.log(i);
}

Những chú thích đó không nói với người đọc điều gì mà code chưa nói. So sánh với:

// Stripe caps description at 500 chars - truncate before sending
function prepareDescription(text) {
    return text.slice(0, 500);
}

// Retry once: the auth service has a known cold-start timeout on first request
async function fetchUser(id) {
    try {
        return await api.get(`/users/${id}`);
    } catch {
        return await api.get(`/users/${id}`);
    }
}

Cả hai chú thích đều nhắc đến điều mà người đọc không thể tự suy ra chỉ từ code: một ràng buộc bên ngoài, một hành vi đặc biệt đã được ghi nhận. Đó là tiêu chuẩn. Nếu xóa chú thích đi mà không ai bối rối, thì chú thích đó không đáng để giữ.

JSDoc: chú thích mà công cụ đọc được

JSDoc là một quy ước viết chú thích khối để mô tả hàm theo cách có cấu trúc. Trình soạn thảo và công cụ kiểm tra kiểu đọc chúng và cho bạn gợi ý tự động hoàn thành cùng tài liệu khi rê chuột tốt hơn:

/**
 * Returns the final price after applying a percentage discount.
 *
 * @param {number} price - The original price in cents.
 * @param {number} percent - Discount percentage, 0 to 100.
 * @returns {number} The discounted price in cents.
 */
function discount(price, percent) {
    return price * (1 - percent / 100);
}

console.log(discount(10000, 20));

Phần mở đầu /** (hai dấu sao) là thứ đánh dấu đây là JSDoc chứ không phải chú thích khối thông thường. Bạn không cần JSDoc cho mọi hàm: nó đáng giá nhất với API công khai, các tiện ích dùng chung, và những chỗ mà kiểu dữ liệu chưa hiển nhiên từ code.

Vài thói quen nên giữ

• Đặt chú thích gần đoạn code nó mô tả. Chú thích nằm cách dòng liên quan mười dòng dễ bị lệch khi code thay đổi.
• Cập nhật chú thích khi bạn sửa code. Chú thích lỗi thời còn tệ hơn không có chú thích: nó nói dối người đọc tiếp theo.
• Ưu tiên đặt tên tốt hơn là viết thêm chú thích. const d = 86400000; cần chú thích. const MILLISECONDS_PER_DAY = 86_400_000; thì không.
• Đánh dấu vấn đề tạm thời bằng TODO: hoặc FIXME:. Hầu hết trình soạn thảo đều tô sáng chúng, và chúng dễ tìm bằng grep về sau.

// TODO: handle timezone offsets properly once the date library is upgraded
function daysBetween(a, b) {
    const MS_PER_DAY = 86_400_000;
    return Math.round((b - a) / MS_PER_DAY);
}

const start = new Date("2024-01-01");
const end = new Date("2024-01-15");
console.log(daysBetween(start, end));

Lưu ý về chú thích HTML và JavaScript

Nếu bạn viết JavaScript bên trong tệp HTML, đừng nhầm hai kiểu chú thích. HTML dùng <!-- -->; JavaScript dùng // và /* */. Bên trong thẻ <script>, chỉ các dạng của JavaScript mới có tác dụng:

<script>
    // Correct - JS comment inside <script>
    /* Also correct */
    <!-- Wrong - this is an HTML comment and will break your JS -->
    console.log("hi");
</script>

Vì lý do lịch sử từ các trình duyệt rất cũ, trình duyệt từng chấp nhận <!-- --> bên trong script, nhưng hãy coi đó là cách viết hỏng và đừng dùng.

Tiếp theo: khai báo biến

Giờ bạn đã biết cách chú thích code, đến lúc viết code thôi. JavaScript có ba cách khai báo biến, let, const và var, và chọn đúng cách là quyết định thật sự đầu tiên bạn đưa ra trên mỗi dòng code. Đó là nội dung tiếp theo.