10 tháng 9, 2024
Hiện có! Đây là một phiên bản nhẹ khi tôi học thêm về định dạng một cuốn sách đẹp mắt. Bạn có thể xem một số sự khác biệt giữa v2 và v3 tại đây.
Code is written in a structured machine language, comments are written in an expressive human language. The "human language" bit makes comments more expressive and communicative than code. Code has a limited amount of something like human language contained in identifiers. "Comment the why, not the what" means to push as much information as possible into identifiers. Không phải tất cả "what" đều có thể được nhúng như thế này, nhưng nhiều cái có thể.
Trong những năm gần đây, tôi thấy ngày càng nhiều người tranh luận rằng lý do cũng không nên có trong các bình luận, rằng chúng có thể được nhúng vào LongFunctionNames hoặc tên của các trường hợp kiểm tra. Hầu như tất cả các mã nguồn "tự tài liệu" đều thêm tài liệu thông qua việc bổ sung các định danh.1
Vậy có điều gì trong phạm vi biểu đạt của con người mà không thể được thể hiện bằng nhiều mã hơn?
Thông tin tiêu cực, thu hút sự chú ý đến những gì không có ở đó. Những "tại sao không" của hệ thống.
Một Ví Dụ Gần Đây
Đoạn này đến từ Logic for Programmers. Vì những lý do kỹ thuật phức tạp, việc xây dựng epub không chuyển đổi ký hiệu toán học (\forall) thành các ký hiệu (∀). Tôi đã viết một kịch bản để đi qua và thay thế các token trong chuỗi toán học bằng các ký hiệu unicode tương ứng. Cách dễ nhất để làm điều này là gọi string = string.replace(old, new) cho mỗi một trong 16 ký hiệu toán học mà tôi cần thay thế (một số chuỗi toán học có nhiều ký hiệu).
Điều này cực kỳ không hiệu quả và tôi có thể thực hiện tất cả 16 thay thế trong một lần duy nhất. Nhưng đó sẽ là một giải pháp phức tạp hơn. Vì vậy, tôi đã làm theo cách đơn giản với một nhận xét:
Có 16 lần lặp qua mỗi chuỗi nhưng hiện tại chỉ có 25 chuỗi toán học trong cuốn sách và hầu hết đều <5>
Bạn có thể nghĩ về điều này như là "tại sao tôi sử dụng mã chậm", nhưng bạn cũng có thể nghĩ về nó như là "tại sao không phải mã nhanh". Nó đang thu hút sự chú ý đến một cái gì đó không có ở đó.
Tại sao lại là bình luận
Nếu mã chậm không gây ra bất kỳ vấn đề gì, tại sao lại có một bình luận?
Trước hết, mã có thể là một vấn đề sau này. Nếu một phiên bản tương lai của LfP có hàng trăm chuỗi toán học thay vì chỉ vài chục thì bước xây dựng này sẽ làm tắc nghẽn toàn bộ quá trình xây dựng. Tốt hơn là nên đặt một biển chỉ dẫn ngay bây giờ để tôi biết chính xác những gì cần sửa sau này.
Nhưng ngay cả khi mã vẫn ổn mãi mãi, bình luận vẫn làm một điều quan trọng: nó cho thấy tôi nhận thức được sự đánh đổi. Giả sử tôi quay lại dự án của mình sau hai năm, mở epub_math_fixer.py và thấy mã của mình chậm chạp đến mức nào. Tôi tự hỏi "tại sao tôi lại viết một thứ tồi tệ như vậy?" Có phải do thiếu kinh nghiệm, áp lực thời gian, hay chỉ là một sai lầm ngẫu nhiên?
Nhận xét tiêu cực cho tôi biết rằng tôi biết đây là mã chậm, đã xem xét các lựa chọn thay thế và quyết định không tối ưu hóa. Tôi không cần phải dành nhiều thời gian để điều tra lại chỉ để đi đến cùng một kết luận.
Tại sao điều này không thể tự tài liệu hóa
Khi tôi lần đầu tiên chơi với ý tưởng này, ai đó đã nói với tôi rằng nhận xét tiêu cực của tôi là không cần thiết, chỉ cần đặt tên hàm là RunFewerTimesSlowerAndSimplerAlgorithmAfterConsideringTradeOffs. Ngoài những vấn đề về việc tên quá dài, không giải thích các sự đánh đổi, và rằng tôi sẽ phải thay đổi nó ở mọi nơi nếu tôi bao giờ tối ưu hóa mã... Điều này sẽ làm cho mã ít tự tài liệu hơn. Nó không cho bạn biết hàm thực sự làm gì.
Vấn đề cốt lõi là các định danh hàm và biến chỉ có thể chứa một mệnh đề thông tin. Tôi không thể lưu trữ "chức năng của hàm" và "các sự đánh đổi mà nó thực hiện" trong cùng một định danh.
Thế còn việc thay thế bình luận bằng một bài kiểm tra thì sao. Tôi đoán bạn có thể tạo một bài kiểm tra mà tìm kiếm các khối toán trong cuốn sách và thất bại nếu có hơn 80? Nhưng điều đó không kiểm tra EpubMathFixer trực tiếp. Không có gì trong chính hàm đó mà bạn có thể gắn vào.
Đó là vấn đề cơ bản với thông tin tiêu cực tự tài liệu. "Tự tài liệu" đi kèm với mã viết, và do đó mô tả những gì mã đang làm. Thông tin tiêu cực là về những gì mã không làm.
Kết thúc suy đoán về bản tin
Tôi tự hỏi liệu bạn có thể coi các bình luận "tại sao không" như một trường hợp của các giả thuyết phản thực tế không. Nếu vậy, liệu "các trừu tượng của giao tiếp con người" có phải là không thể tự tài liệu hóa một cách tổng quát không? Bạn có thể tự tài liệu hóa một phép so sánh không? Sự không chắc chắn? Một tuyên bố đạo đức?