- Vì sao không có bình luận kiểu "tại sao không"? Không phải vì sao "không có bình luận"
- “Vì sao bạn không để lại chú thích về ‘vì sao điều đó không hoạt động’? Tôi không hỏi lý do ‘vì sao bạn không viết chú thích’.”
Vì sao không có bình luận kiểu “tại sao không”
- Mã được viết bằng ngôn ngữ máy có cấu trúc, còn chú thích được viết bằng ngôn ngữ con người giàu khả năng biểu đạt
- Ý này muốn nói rằng đừng chú thích về "cái gì", mà hãy đưa càng nhiều thông tin càng tốt vào các định danh
- Gần đây còn có ý kiến cho rằng đừng đưa cả "vì sao" vào chú thích, mà hãy nhét vào
LongFunctionNames hoặc tên test case
- Codebase "tự mô tả" là kiểu thêm tài liệu thông qua các định danh
Ví dụ gần đây
- Ví dụ từ
Logic for Programmers
- Quá trình build epub gặp vấn đề khi không thể chuyển ký hiệu toán học (
\forall) thành biểu tượng (∀)
- Đã viết một script để thay thế thủ công các token trong chuỗi toán học sang Unicode
- Script được viết theo cách thay thế riêng từng ký hiệu trong số 16 ký hiệu toán học, nhưng cách này không hiệu quả
- Vấn đề được giải quyết bằng cách thêm một chú thích đơn giản
- "Lặp 16 lần cho mỗi chuỗi, nhưng hiện tại cuốn sách chỉ có 25 chuỗi toán học và phần lớn ngắn hơn 5 ký tự, nên vẫn đủ nhanh"
Vì sao nên viết chú thích
- Vì sao vẫn nên viết chú thích ngay cả khi mã chậm chưa gây ra vấn đề
- Trong tương lai, đoạn mã đó có thể trở thành vấn đề
- Chú thích cho thấy bạn nhận thức được các đánh đổi
- Khi quay lại dự án sau này, bạn có thể hiểu vì sao mình đã viết đoạn mã chậm đó
Vì sao không thể tự mô tả hoàn toàn
- Những tên hàm dài như "RunFewerTimesSlowerAndSimplerAlgorithmAfterConsideringTradeOffs" không giải thích được các đánh đổi
- Định danh của hàm và biến chỉ có thể chứa một loại thông tin
- Cũng không thể thay thế chú thích bằng test
- Tự mô tả chỉ giải thích mã làm gì, còn thông tin phủ định lại giải thích mã không làm gì
Suy đoán ở cuối bản tin
- Tác giả tự hỏi liệu có thể xem các chú thích kiểu "vì sao không" như những trường hợp phản thực tế hay không
- Liệu mức độ trừu tượng trong giao tiếp của con người có khiến việc tự mô tả trở nên bất khả thi?
- Có thể tự mô tả các phép ẩn dụ, sự bất định, hay các lập luận đạo đức hay không?
Tổng hợp của GN⁺
- Bài viết này bàn về tầm quan trọng của chú thích trong mã và những giới hạn của chúng
- Chú thích giúp làm rõ các đánh đổi trong mã và giúp việc bảo trì về sau dễ dàng hơn
- Bài viết nhấn mạnh giới hạn của code tự mô tả và sự cần thiết của chú thích
1 bình luận
Ý kiến trên Hacker News
Khi viết chú thích trong code, chủ yếu giải thích "tại sao" và "tại sao không làm được". Với code phức tạp, giải thích ngắn gọn "cái gì" cũng hữu ích
Kỹ sư junior viết chú thích giải thích code làm gì, kỹ sư cấp trung giải thích vì sao lại viết như vậy, còn kỹ sư senior giải thích vì sao không viết theo cách khác
Sử dụng mẫu chú thích dành cho người bảo trì
Việc chú thích những phần gây bất ngờ trong code là rất quan trọng
Nhấn mạnh tầm quan trọng của chú thích, đặc biệt hữu ích khi chính bạn phải bảo trì code của mình sau 5, 10, 15 năm
Nên chú thích những chỗ "không phải là lời giải ngây thơ"
Nên đưa chú thích vào tên hàm dài hoặc tên test case
Việc thêm cảnh báo qua debug logging khi đầu vào lớn hơn các ràng buộc thiết kế ban đầu cũng rất hữu ích
Thích sử dụng nhiều chú thích và chú thích tài liệu
Trong code review, để ngăn trước những lời phê bình có thể xuất hiện, hãy viết chú thích kiểu "Lý do không làm X là vì Y"