Bình luận: khi nào cần

Sửa code trước khi thêm comment

// TRUOC: comment giai thich "cai gi" - phai doc ca hai dong moi hieu
function check(u: User): boolean {
  // kiem tra nguoi dung con hoat dong va dang ky duoi 30 ngay
  return u.active && u.daysRegistered < 30;
}

// SAU: ten ham noi ro y dinh - comment tro nen du thua
function isNewActiveUser(u: User): boolean {
  return u.active && u.daysRegistered < 30;
}

Các loại comment xấu thường gặp

// 1. DU THUA - noi dung y chang code, khong them gi
let count = 0; // khoi tao bien count bang 0

// 2. LOI THOI - code da doi nhung comment chua cap nhat (nguy hiem nhat)
// Tinh thue VAT 10% theo luat cu
function calcTax(amount: number): number {
  return amount * 0.08; // thuc te da doi sang 8% tu thang truoc
}

// 3. CODE BI COMMENT-OUT - khong ai biet co the xoa chua; dung git thay vi day
// function oldValidate(x: string) { ... }
// const legacyFlag = true;

// 4. CHU KY / NHAT KY - git log lam viec nay roi
// Nguyen - 2024-01-15: them truong email
// Minh - 2024-02-03: sua bug validate

// 5. GAY NHIEU - comment that dai, khong them thong tin gi
// Ham nay nhan mot mang cac phan tu kieu so va tra ve tong
// cua tat ca cac phan tu trong mang do
function sum(nums: number[]): number {
  return nums.reduce((a, b) => a + b, 0);
}

Các loại comment tốt - giải thích ý định, cảnh báo, TODO rõ ràng

// 1. GIAI THICH VI SAO - ly do kinh doanh khong the doc tu code
// Dung setTimeout de tranh race condition voi animation CSS:
// neu cap nhat DOM ngay, transition chua chay xong se bi reset.
setTimeout(() => updateDOM(), 50);

// 2. CANH BAO HAU QUA - nguoi doc can biet truoc khi sua
// CANH BAO: ham nay khong thread-safe; chi goi tu worker thread chinh.
// Goi tu nhieu thread cung luc se gay data race tren sharedBuffer.
function writeToSharedBuffer(data: Uint8Array): void { /* ... */ }

// 3. TODO RO RANG - viec gi, tai sao chua lam, ai chiu trach nhiem
// TODO(nguyen): chuyen sang crypto.randomUUID() sau khi drop support Node 14
const id = Math.random().toString(36).slice(2);

// 4. LAM RO BIEU THUC KHO - khi bien/ham khong the ro hon duoc
// Kiem tra ngay thu trong tuan theo UTC, khong phai local time
// vi server va client co the o cac timezone khac nhau.
const isWeekend = [0, 6].includes(new Date(ts).getUTCDay());

Kiểu thay thế được nhiều comment mô tả

// TRUOC: comment mo ta tham so va gia tri tra ve
// @param userId - ID cua nguoi dung (so nguyen duong)
// @param role - vai tro: 'admin', 'editor', hoac 'viewer'
// @returns true neu cap quyen thanh cong
function grantAccess(userId: any, role: any): any { /* ... */ }

// SAU: kieu noi thay - comment mo ta tro thanh du thua
type UserId = number;
type Role = 'admin' | 'editor' | 'viewer';

function grantAccess(userId: UserId, role: Role): boolean { /* ... */ }
// Goi sai kieu: grantAccess('abc', 'superuser') -> loi bien dich ngay

JSDoc hợp lý cho hàm public - nói điều kiểu không nói được

/**
 * Chuyen doi so tien VND sang chuoi hien thi co phan cach hang nghin.
 *
 * @param amount - So tien (phai >= 0; am -> nem RangeError)
 * @param currency - Ma tien te ISO 4217, mac dinh 'VND'
 * @returns Chuoi dang "1.500.000 VND"
 * @throws {RangeError} Neu amount < 0
 *
 * @example
 * formatMoney(1500000) // => "1.500.000 VND"
 * formatMoney(250, 'USD') // => "250 USD"
 */
function formatMoney(amount: number, currency = 'VND'): string {
  if (amount < 0) throw new RangeError('amount phai >= 0');
  return amount.toLocaleString('vi-VN') + ' ' + currency;
}