Tôi thường coi những bình luận như vậy là một thông lệ xấu và tôi nghĩ loại thông tin này thuộc về nhật ký cam kết SCM. Nó chỉ làm cho mã khó đọc hơn trong hầu hết các trường hợp.
Tuy nhiên , tôi vẫn thường làm một cái gì đó như thế này cho các loại chỉnh sửa cụ thể.
Trường hợp 1 - Nhiệm vụ
Nếu bạn sử dụng một IDE như Eclipse, Netbeans, Visual Studio (hoặc có một số cách thực hiện tìm kiếm văn bản trên cơ sở mã của bạn với bất cứ điều gì khác), có thể nhóm của bạn sử dụng một số "thẻ nhận xét" hoặc "thẻ nhiệm vụ" cụ thể. Trong trường hợp này có thể hữu ích.
Thỉnh thoảng, khi xem lại mã, hãy thêm một số thứ như sau:
// TOREVIEW: [2010-12-09 haylem] marking this for review because blablabla
hoặc là:
// FIXME: [2010-12-09 haylem] marking this for review because blablabla
Tôi sử dụng các thẻ tác vụ tùy chỉnh khác nhau mà tôi có thể thấy trong Eclipse trong khung nhìn tác vụ cho điều này, bởi vì có một cái gì đó trong nhật ký cam kết là một điều tốt nhưng không đủ khi bạn có một giám đốc điều hành hỏi bạn trong một cuộc họp đánh giá tại sao lỗi bug XY hoàn toàn bị lãng quên và trượt qua. Vì vậy, đối với các vấn đề khẩn cấp hoặc các đoạn mã thực sự đáng nghi ngờ, đây là một lời nhắc bổ sung (nhưng thông thường tôi sẽ giữ bình luận ngắn và kiểm tra nhật ký cam kết vì đó là những gì nhắc nhở ở đây, vì vậy tôi cũng không làm lộn xộn mã nhiều).
Trường hợp 2 - Bản vá lỗi của Libs bên thứ 3
Nếu sản phẩm của tôi cần gói một đoạn mã của bên thứ 3 dưới dạng nguồn (hoặc thư viện, nhưng được xây dựng lại từ nguồn) vì nó cần được vá vì một số lý do, chúng tôi sẽ ghi lại bản vá trong một tài liệu riêng biệt trong đó chúng tôi liệt kê các "cảnh báo" đó để tham khảo trong tương lai và mã nguồn thường sẽ chứa một nhận xét tương tự như:
// [PATCH_START:product_name]
// ... real code here ...
// [PATCH_END:product_name]
Trường hợp 3 - Sửa lỗi không rõ ràng
Điều này gây tranh cãi hơn một chút và gần hơn với những gì nhà phát triển cấp cao của bạn đang yêu cầu.
Trong sản phẩm tôi làm việc tại thời điểm này, đôi khi chúng tôi (chắc chắn không phải là một điều phổ biến) có một nhận xét như:
// BUGFIX: [2010-12-09 haylem] fix for BUG_ID-XYZ
Chúng tôi chỉ làm điều này nếu lỗi không rõ ràng và mã đọc bất thường. Ví dụ, đây có thể là trường hợp đối với các yêu cầu của trình duyệt hoặc các bản sửa lỗi CSS tối nghĩa mà bạn cần thực hiện chỉ vì có lỗi tài liệu trong sản phẩm. Vì vậy, nói chung, chúng tôi sẽ liên kết nó với kho lưu trữ vấn đề nội bộ của chúng tôi, sau đó sẽ chứa lý do chi tiết đằng sau lỗi và con trỏ đến tài liệu về lỗi của sản phẩm bên ngoài (giả sử, một lời khuyên bảo mật cho lỗi Internet Explorer 6 nổi tiếng, hoặc đại loại như thế).
Nhưng như đã đề cập, nó khá hiếm. Và nhờ các thẻ tác vụ, chúng tôi có thể thường xuyên chạy qua các thẻ này và kiểm tra xem các bản sửa lỗi kỳ lạ này có còn ý nghĩa hay có thể được loại bỏ hay không (ví dụ: nếu chúng tôi bỏ hỗ trợ cho sản phẩm lỗi gây ra lỗi ngay từ đầu).
Điều này chỉ trong: Một ví dụ thực tế cuộc sống
Trong một số trường hợp, tốt hơn là không có gì :)
Tôi vừa bắt gặp một lớp tính toán thống kê khổng lồ trong cơ sở mã của mình, trong đó nhận xét tiêu đề ở dạng thay đổi với yadda yadda thông thường: người đánh giá, ngày tháng, ID lỗi.
Lúc đầu, tôi nghĩ đến việc loại bỏ nhưng tôi nhận thấy ID lỗi không những không phù hợp với quy ước của trình theo dõi vấn đề hiện tại của chúng tôi mà còn không khớp với trình theo dõi được sử dụng trước khi tôi gia nhập công ty. Vì vậy, tôi đã cố gắng đọc qua mã và hiểu được những gì lớp đang làm (không phải là một nhà thống kê) và cũng đã cố gắng khai thác các báo cáo khiếm khuyết này. Khi điều đó xảy ra, họ khá quan trọng và sẽ đánh lừa cuộc sống của anh chàng tiếp theo để chỉnh sửa tập tin mà không biết về họ khá kinh khủng, vì nó xử lý các vấn đề chính xác nhỏ và các trường hợp đặc biệt dựa trên các yêu cầu rất cụ thể được phát ra từ khách hàng ban đầu. . Điểm mấu chốt, nếu những thứ này không có ở đó, tôi sẽ không biết. Nếu họ không ở đó VÀ tôi đã hiểu rõ hơn về lớp học,
Đôi khi thật khó để theo dõi các yêu cầu rất cũ như thế này. Cuối cùng, những gì tôi đã làm vẫn là loại bỏ tiêu đề, nhưng sau khi lén đọc một bình luận khối trước mỗi hàm phân biệt mô tả lý do tại sao các tính toán "kỳ lạ" này là những yêu cầu cụ thể.
Vì vậy, trong trường hợp đó tôi vẫn coi đây là một thực hành tồi, nhưng cậu bé rất vui vì nhà phát triển ban đầu ít nhất đã đưa chúng vào! Thay vào đó, tốt hơn là bình luận mã rõ ràng, nhưng tôi đoán điều đó tốt hơn là không có gì.