Các trích dẫn Robert C. Martin được đưa ra khỏi bối cảnh. Đây là trích dẫn với một chút bối cảnh:
Không có gì có thể khá hữu ích như một bình luận được đặt tốt. Không có gì có thể làm lộn xộn một mô-đun nhiều hơn những bình luận giáo điều phù phiếm. Không có gì có thể gây tổn hại lớn như một bình luận cũ nát mà tuyên truyền dối trá và thông tin sai lệch.
Nhận xét không giống như Danh sách của Schindler. Họ không phải là "tốt thuần túy." Thật vậy, bình luận, tốt nhất, là một điều ác cần thiết. Nếu ngôn ngữ lập trình của chúng tôi đủ biểu cảm hoặc nếu chúng tôi có tài năng khéo léo sử dụng các ngôn ngữ đó để thể hiện ý định của mình, chúng tôi sẽ không cần bình luận nhiều - có lẽ không phải vậy.
Việc sử dụng đúng các bình luận là để bù đắp cho sự thất bại của chúng tôi trong việc thể hiện chính chúng ta trong mã. Lưu ý rằng tôi đã sử dụng từ thất bại. Ý tôi là thế Bình luận luôn là thất bại. Chúng ta phải có chúng bởi vì chúng ta không thể luôn luôn tìm ra cách thể hiện bản thân mà không có chúng, nhưng việc sử dụng chúng không phải là một nguyên nhân cho lễ kỷ niệm.
Vì vậy, khi bạn thấy mình ở một vị trí mà bạn cần viết bình luận, hãy suy nghĩ kỹ và xem liệu không có cách nào để xoay bảng và thể hiện bản thân bằng mã. Mỗi khi bạn thể hiện bản thân bằng mã, bạn nên vỗ nhẹ vào lưng. Mỗi khi bạn viết bình luận, bạn nên nhăn nhó và cảm nhận sự thất bại trong khả năng diễn đạt của mình.
(Sao chép từ đây , nhưng trích dẫn ban đầu là từ Clean Code: A Handbook of Agile Software Crafts )
Làm thế nào trích dẫn này được giảm thành "Bình luận luôn luôn thất bại" là một ví dụ tốt về cách một số người sẽ đưa ra một trích dẫn hợp lý ra khỏi bối cảnh và biến nó thành giáo điều ngu ngốc.
Tài liệu API (như javadoc) được cho là tài liệu API để người dùng có thể sử dụng nó mà không cần phải đọc mã nguồn . Vì vậy, trong trường hợp này, tài liệu nên giải thích những gì phương pháp làm. Bây giờ bạn có thể lập luận rằng "Lấy một sản phẩm theo id của nó" là không cần thiết bởi vì nó đã được chỉ định bởi tên phương thức, nhưng thông tin nullcó thể được trả về chắc chắn rất quan trọng đối với tài liệu, vì điều này không rõ ràng.
Nếu bạn muốn tránh sự cần thiết của nhận xét, bạn phải loại bỏ vấn đề tiềm ẩn (đó là việc sử dụng nulllàm giá trị trả về hợp lệ), bằng cách làm cho API rõ ràng hơn. Ví dụ: bạn có thể trả về một số loại Option<Product>, vì vậy chữ ký loại tự truyền đạt rõ ràng những gì sẽ được trả lại trong trường hợp không tìm thấy sản phẩm.
Nhưng trong mọi trường hợp, việc ghi lại API hoàn toàn chỉ thông qua tên phương thức và chữ ký loại là không thực tế. Sử dụng nhận xét tài liệu cho bất kỳ thông tin không rõ ràng bổ sung nào mà người dùng nên biết. Hãy nói rằng tài liệu API từ DateTime.AddMonths()trong BCL:
Phương thức AddMonths tính toán tháng và năm kết quả, có tính đến năm nhuận và số ngày trong một tháng, sau đó điều chỉnh phần ngày của đối tượng DateTime kết quả. Nếu ngày kết quả không phải là ngày hợp lệ trong tháng kết quả, ngày hợp lệ cuối cùng của tháng kết quả sẽ được sử dụng. Ví dụ: ngày 31 tháng 3 + 1 tháng = ngày 30 tháng 4. Phần thời gian trong ngày của đối tượng DateTime kết quả vẫn giống như trường hợp này.
Không có cách nào bạn có thể diễn tả điều này bằng cách chỉ sử dụng tên phương thức và chữ ký! Tất nhiên tài liệu lớp học của bạn có thể không yêu cầu mức độ chi tiết này, nó chỉ là một ví dụ.
Bình luận nội tuyến cũng không tệ.
Xấu comments là xấu. Ví dụ các bình luận chỉ giải thích những gì có thể nhìn thấy một cách tầm thường từ mã, ví dụ cổ điển là:
// increment x by one
x++;
Nhận xét giải thích điều gì đó có thể được làm rõ bằng cách đổi tên một biến hoặc phương thức hoặc cơ cấu lại mã, là một mùi mã:
// data1 is the collection of tasks which failed during execution
var data1 = getData1();
Đây là những loại bình luận Martin chống lại. Nhận xét là một triệu chứng của việc không viết mã rõ ràng - trong trường hợp này là sử dụng tên tự giải thích cho các biến và phương thức. Bản thân bình luận tất nhiên không phải là vấn đề, vấn đề là chúng ta cần bình luận để hiểu mã.
Nhưng các bình luận nên được sử dụng để giải thích mọi thứ không rõ ràng từ mã, ví dụ tại sao mã được viết theo một cách không rõ ràng nhất định:
// need to reset foo before calling bar due to a bug in the foo component.
foo.reset()
foo.bar();
Các bình luận giải thích những gì một đoạn mã quá phức tạp cũng là một mùi, nhưng cách khắc phục không phải là ngoài ý kiến, sửa lỗi là sửa mã! Nói một cách thực tế, mã phức tạp đã xảy ra (hy vọng chỉ là tạm thời cho đến khi tái cấu trúc) nhưng không có nhà phát triển bình thường nào viết mã sạch hoàn hảo ngay lần đầu tiên. Khi mã phức tạp xảy ra, tốt hơn là viết bình luận giải thích những gì nó làm hơn là không viết bình luận. Nhận xét này cũng sẽ làm cho nó dễ dàng hơn để tái cấu trúc sau này.
Đôi khi mã là không thể tránh khỏi phức tạp. Nó có thể là một thuật toán phức tạp, hoặc nó có thể là mã hy sinh sự rõ ràng vì lý do hiệu suất. Một lần nữa ý kiến là cần thiết.