Chú thích tốt giải thích vì sao, không lặp lại cái gì. Mã đã tự nói nó làm gì rồi. Chú thích nên nói lý do, bối cảnh, những cảnh báo mà người sau cần biết, và những cách làm khác đã được cân nhắc rồi loại bỏ. Và nhớ rằng chú thích sai còn tệ hơn không có chú thích.
Chào bạn, đây là Nhà Lập Trình. Hồi mới học, nhiều bạn được dạy rằng chú thích càng nhiều càng tốt, mỗi dòng mã một dòng chú thích. Đi làm vài năm, cũng những bạn đó lại nghe người khác nói mã tốt không cần chú thích. Cả hai đều chưa đúng hẳn. Tập này mình kể chú thích nào đáng viết.
Chú thích lặp lại mã là tiếng ồn
Hãy hình dung một dòng mã cộng thêm một vào biến đếm, và phía trên có chú thích: cộng một vào biến đếm. Chú thích này không cho người đọc thêm thông tin gì. Nó chỉ làm mã dài hơn, và khiến người đọc phải đọc hai lần cùng một điều.
Loại chú thích này hay xuất hiện ở người mới, vì được dặn phải chú thích. Nó cũng hay xuất hiện trong mã được sinh tự động. Nó vô hại khi mới viết, nhưng có hại về lâu dài.
Vì sao có hại? Vì khi đầy chú thích vô nghĩa, người đọc học cách bỏ qua chú thích. Rồi khi có một chú thích thật sự quan trọng, họ cũng bỏ qua nó luôn.
Nếu bạn cảm thấy cần chú thích để giải thích một dòng mã làm gì, hãy thử viết lại dòng đó cho rõ hơn trước: đặt tên biến tốt hơn, tách thành hàm có tên rõ. Mã tự nói được thì không cần chú thích nói thay.
Chú thích đáng giá nhất: vì sao
Có một thứ mã không bao giờ nói được: vì sao nó được viết như vậy. Và đây chính là thứ người đọc sau cần nhất.
Hãy hình dung một đoạn mã chờ hai giây rồi thử lại khi gọi dịch vụ thanh toán thất bại. Nhìn mã, ai cũng thấy nó chờ hai giây. Nhưng vì sao hai giây, không phải một hay năm? Một dòng chú thích nói rằng dịch vụ thanh toán yêu cầu chờ ít nhất hai giây giữa các lần thử, nếu không sẽ bị khoá tạm thời, sẽ ngăn người sau đổi nó thành một giây cho nhanh.
Những lựa chọn trông lạ luôn cần chú thích. Một cách làm vòng vo trong khi có cách trông đơn giản hơn. Một giá trị đặt cứng có vẻ tuỳ tiện. Một điều kiện kiểm tra một trường hợp có vẻ không bao giờ xảy ra. Mỗi thứ như vậy là một câu hỏi vì sao trong đầu người đọc. Hãy trả lời trước cho họ.
Nếu có, hãy ghi cả những cách đã thử và bị loại: đã thử dùng thư viện kia nhưng nó không xử lý được tiếng Việt có dấu. Dòng này cứu người sau khỏi mất một buổi chiều thử lại đúng điều đó.
Cảnh báo và giới hạn
Loại chú thích quý thứ hai là cảnh báo. Hàm này không an toàn khi gọi từ nhiều luồng cùng lúc. Đổi thứ tự hai dòng này sẽ làm sai số dư. Bảng này có hàng triệu dòng, đừng quét toàn bộ.
Những cảnh báo này ghi lại kiến thức mà người viết đã phải trả giá để có. Có khi là sau một đêm sự cố. Không ghi lại, người sau sẽ phải trả giá lần nữa.
Giới hạn cũng cần ghi. Hàm này chỉ xử lý được số tiền tới mức nào. Chỉ đúng với múi giờ Việt Nam. Chưa xử lý trường hợp khách hàng có nhiều địa chỉ. Người đọc biết giới hạn sẽ không dùng hàm sai chỗ.
Những việc còn dang dở cũng nên ghi, nhưng ghi cụ thể: việc gì, vì sao chưa làm, khi nào nên làm. Một dòng ghi làm sau không kèm gì cả sẽ nằm đó mãi, không ai biết làm gì.
Chú thích lỗi thời nguy hiểm hơn không có
Mã thay đổi liên tục, còn chú thích thì hay bị bỏ quên. Người sửa mã đổi logic, nhưng không để ý dòng chú thích bên trên. Thế là chú thích nói một đằng, mã làm một nẻo.
Chú thích sai nguy hiểm vì người đọc tin nó. Họ đọc chú thích thấy hàm trả về danh sách rỗng khi không có kết quả, nên không kiểm tra trường hợp hàm trả về giá trị trống. Thực tế hàm đã được sửa để trả về giá trị trống từ lâu. Lỗi xảy ra.
Quy tắc đơn giản: sửa mã thì đọc lại chú thích xung quanh, và sửa chú thích nếu nó không còn đúng. Khi xem lại mã cho đồng nghiệp, hãy để ý cả chú thích, không chỉ mã.
Đây cũng là lý do nên viết ít chú thích nhưng chất lượng. Mỗi chú thích là một thứ cần bảo trì. Chú thích vô nghĩa không chỉ làm ồn, mà còn là gánh nặng bảo trì không đáng.
Chú thích cho người dùng hàm
Có một loại chú thích khác hẳn: chú thích mô tả cách dùng một hàm hay một thành phần, dành cho người gọi nó chứ không phải người sửa nó. Hàm này nhận gì, trả về gì, ném ra lỗi gì, có tác dụng phụ gì.
Loại này đặc biệt quan trọng với những hàm được dùng ở nhiều nơi, những thư viện chung của đội. Người gọi không nên phải đọc toàn bộ phần thân hàm để biết cách dùng.
Nhiều ngôn ngữ có quy ước riêng cho loại chú thích này, và công cụ có thể đọc nó để hiện gợi ý ngay trong trình soạn thảo hoặc sinh ra tài liệu. Theo quy ước đó sẽ có lợi nhiều mặt.
Viết chú thích giống như để lại lời nhắn cho người sẽ ở căn nhà sau mình. Không cần kể mọi thứ trong nhà có gì, họ tự nhìn thấy. Chỉ cần dặn những điều họ không tự thấy được: ống nước này hay rò, công tắc kia không nên bật cùng lúc với máy lạnh.
Câu hỏi thường gặp
Mã tốt có cần chú thích không?
Mã tốt ít cần chú thích giải thích nó làm gì, vì tên và cấu trúc đã tự nói. Nhưng vẫn cần chú thích giải thích vì sao, cảnh báo và giới hạn, vì những điều đó mã không tự nói được.
Nên viết chú thích bằng tiếng Việt hay tiếng Anh?
Theo quy ước của đội và theo người sẽ đọc. Đội toàn người Việt có thể viết tiếng Việt cho rõ ý. Dự án mở hoặc có đồng nghiệp nước ngoài thì nên dùng tiếng Anh.
Chú thích làm sau trong mã có nên dùng không?
Có thể dùng, nhưng nên ghi cụ thể việc gì, vì sao chưa làm và khi nào nên làm. Nên định kỳ rà lại để những ghi chú này không bị bỏ quên mãi.
Có nên để lại đoạn mã cũ đã tắt bằng chú thích không?
Không nên. Mã cũ đã có trong lịch sử thay đổi, để lại trong tệp chỉ gây rối. Nếu cần giải thích vì sao bỏ, hãy ghi trong lời nhắn thay đổi.
Làm sao tránh chú thích bị lỗi thời?
Viết ít chú thích nhưng có giá trị, đặt chú thích sát chỗ mã liên quan, và tập thói quen đọc lại chú thích mỗi khi sửa mã. Khi xem lại mã cho đồng nghiệp, hãy kiểm tra cả chú thích.
