Tôi thấy nhiều số vấn đề từ các bình luận về mã jQuery . (Trên thực tế, có 69 số vấn đề trong mã jQuery.) Tôi nghĩ rằng đó sẽ là một cách thực hành tốt, nhưng tôi chưa bao giờ thấy bất kỳ hướng dẫn nào.
Nếu đó là một thực hành tốt, các hướng dẫn cho thực hành này là gì?
Câu trả lời:
Nói chung, tôi sẽ không coi đó là thực hành tốt. Nhưng trong những trường hợp đặc biệt, nó có thể rất hữu ích, cụ thể là khi mã phải làm điều gì đó không trực quan để khắc phục một vấn đề phức tạp và không có bất kỳ lời giải thích nào sẽ có nguy cơ ai đó muốn "sửa" mã lạ này và do đó phá vỡ nó , trong khi giải thích lý do sẽ dẫn đến một nhận xét lớn trùng lặp thông tin từ vấn đề.
Tôi nghĩ rằng đã đủ để thêm số sự cố vào thông báo cam kết khi bạn cam kết sửa lỗi liên quan đến hệ thống kiểm soát nguồn của mình.
Ví dụ:
Lỗi # 203: Kết nối cơ sở dữ liệu không còn thời gian chờ sau 30 giây.
Tôi thấy rằng việc thêm số vấn đề, tên nhà phát triển hoặc ngày thay đổi đã được thực hiện trong mã chỉ gây ô nhiễm cơ sở mã và thực sự cần được quản lý bên ngoài bởi hệ thống kiểm soát nguồn của bạn.
Tôi hoàn toàn không đồng ý với các áp phích khác ở đây!
Nhận xét mã với các tài liệu tham khảo theo dõi có thể là một trợ giúp lớn cho lập trình bảo trì.
Nếu tôi đang theo dõi một lỗi và đến gần khu vực của mã, để thấy rằng nó gần đây đã được thay đổi và có một liên kết đến bối cảnh của sự thay đổi là một sự gửi gắm.
Có, chúng tôi có kiểm soát mã nguồn, nhưng có thể khá chậm để kiểm tra các tệp và mô-đun riêng lẻ. Bạn muốn những điều này nhảy ra khỏi bạn cho những thay đổi gần đây.
Tôi có thể sẽ phản đối họ khi tôi thấy những cái thực sự cũ trong cơ sở mã, nhưng có rất ít mặt trái để giữ những cái gần đây hơn và rất nhiều thời gian dành cho nhà phát triển có khả năng tiết kiệm nếu bạn sử dụng chúng một cách thông minh.
Tôi thực sự nghĩ rằng những tham chiếu nhỏ này đến hệ thống theo dõi lỗi của bạn là thích hợp hơn cho các bình luận chi tiết trong mã.
git gui blame <filename>cung cấp GUI rất nhanh để duyệt lịch sử mã nếu bạn sử dụng git. Sử dụng một công cụ để kết hợp nhận xét mã với lịch sử cho phép tài liệu mã tốt hơn nhiều so với bất kỳ nhận xét nội tuyến nào có thể. Đó là, nếu bạn bận tâm viết thông điệp cam kết tốt (một thông điệp cam kết tốt sẽ gần bằng với một thông điệp email giải thích lý do tại sao bản vá đó nên được áp dụng).
Nếu bạn đăng ký một chính sách "Mã sạch", thì có lẽ bạn cần phải tự hỏi mình liệu đó có phải là một thực hành tốt để thêm ý kiến hay không. Nếu mã chỉ có thể được làm rõ bằng một nhận xét, thì chắc chắn, hãy thêm một mã, nếu không bạn sẽ có thể dễ dàng hiểu mã của mình làm gì chỉ bằng cách đọc nó (với điều kiện bạn đang sử dụng tên hợp lý cho các biến, phương thức, v.v.).
Bất kể quan điểm cá nhân của bạn về việc bình luận có phải là thông lệ tốt hay không, một bình luận nên chứa thông tin có giá trị trực tiếp với mã mà bình luận đang đề cập. Trong trường hợp này, câu hỏi là liệu việc thêm một số vấn đề có làm tăng giá trị cho mã hay không. Vấn đề tôi thấy khi thêm số vấn đề là bạn có thể có một phần mã có thể được sửa đổi nhiều để đáp ứng một số vấn đề và sau một thời gian, không thể xác định chính xác những thay đổi nào liên quan đến một vấn đề cụ thể. Các vấn đề tiếp theo chẳng hạn có thể yêu cầu mã liên quan đến các vấn đề trước đó phải được tái cấu trúc mạnh mẽ. Đây có lẽ là một ví dụ cực đoan, tuy nhiên nó cho thấy các số vấn đề trong các bình luận trong mã có thể trở nên khá vô dụng.
Nếu bạn có thể đảm bảo rằng tình huống tôi vừa mô tả sẽ không bao giờ xảy ra, tôi vẫn cho rằng bản thân số vấn đề vẫn khá vô dụng nếu không có mô tả về vấn đề này là gì, tuy nhiên, tất cả thông tin này thực sự thuộc về bạn hệ thống theo dõi vấn đề và cần được nhân đôi. Một nơi tốt hơn để lưu ý số vấn đề sẽ có trong hệ thống kiểm soát phiên bản của bạn dưới dạng một nhận xét cam kết. Ưu điểm là bạn có thể so sánh các phiên bản và xem các thay đổi mã liên quan đến một vấn đề cụ thể, trong khi chính số vấn đề cung cấp cho bạn số nhận dạng cần thiết nếu bạn muốn xem lại lý do thay đổi mã.
Với tất cả những điều này, tôi đề nghị rằng nó không thực sự tốt khi thêm số vấn đề vào nhận xét trong mã của bạn.
Tôi nghĩ rằng đó là một thực tiễn tốt để đề cập đến một vấn đề để đọc thêm, trong khi đưa ra một lời giải thích ngắn trong chính nhận xét.
Tôi thường chỉ thêm ý kiến nếu có gì đó tinh tế hoặc không trực quan trong đoạn mã đó. Vì một số vấn đề tế nhị không thể được giải thích hoàn toàn trong một vài dòng và tôi không muốn thêm hàng tá dòng bình luận, tôi sẽ thêm một nhận xét ngắn mô tả những gì điều này đang cố gắng đạt được và đề cập đến vấn đề này chi tiết.
Ví dụ:
// Verify MAC before checking the padding, to avoid padding oracle attacks
// See issue 123 for details
Trường hợp vấn đề 123 mô tả cuộc tấn công đó có thể trông như thế nào và tại sao mã mới miễn nhiễm với cuộc tấn công.
Hoặc là:
// Using foo's algorithm here, since it fits out usage pattern best
// Check issue 345 for a discussion of possible algorithms, and why foo was chosen.
Vấn đề chính với việc đưa số vấn đề vào nguồn của bạn là bây giờ bạn có một tài liệu tham khảo bên ngoài. Vì vậy, bạn cần chắc chắn rằng bạn sẽ không mất vấn đề.
Bao gồm số vấn đề trong thông điệp cam kết có thể rất hữu ích khi mã nguồn của bạn được kết nối với tích hợp liên tục. Các ứng dụng như TeamCity sẽ lấy thông tin đó ra và cho phép báo cáo tốt hơn.
Với những điều đã nói ở trên, tôi không chắc chắn 100% nó lấy từ các bình luận mã. Bao gồm các số vấn đề trong mã hoạt động tốt nếu các số vấn đề vẫn tồn tại (ví dụ: bạn không thay đổi trình theo dõi vấn đề) và bạn không có nhiều vấn đề cho một dự án nhất định.
Có lẽ sẽ hữu ích hơn nếu bạn mô tả vấn đề và giải pháp để nhà phát triển tiếp theo không cần tra cứu số vấn đề. Trình biên dịch hoặc trình khai thác sẽ chỉ xóa các nhận xét của bạn trước khi mã được phát hành tự nhiên, do đó sẽ không có tác động đến kết quả cuối cùng.