Ý tưởng tốt để đặt số lỗi trong một nhận xét vào đầu tệp nguồn? [đóng cửa]

Có phải là một thực hành tốt để đặt số lỗi trong chính tệp trong một nhận xét tiêu đề?

Các ý kiến ​​sẽ trông giống như thế này:

 MODIFIED    (MM/DD/YY)
 abc 01/21/14 - Bug 17452317 - npe in drill across in dashboard edit mode

 cde 01/17/14 - Bug 2314558  - some other error description

Nó có vẻ hữu ích, nhưng nó được coi là thực hành xấu?

Tôi đã thấy điều này được thực hiện trước đây, cả bằng tay bởi các tác giả và tự động bởi các tập lệnh và trình kích hoạt được tích hợp với các hệ thống kiểm soát phiên bản để thêm tác giả, nhận xét đăng ký và thông tin ngày vào tệp.

Tôi nghĩ cả hai phương pháp đều khá khủng khiếp vì hai lý do chính. Đầu tiên, nó thêm sự lộn xộn và tiếng ồn cho tập tin, đặc biệt là khi những bình luận này già đi và trở nên không liên quan đến trạng thái hiện tại của tập tin. Thứ hai, đó là thông tin trùng lặp với những gì đã được duy trì trong hệ thống kiểm soát phiên bản và nếu bạn đang sử dụng hệ thống kiểm soát phiên bản hiện đại hỗ trợ các bộ thay đổi thì thực sự sẽ mất thông tin về các thay đổi.

Nếu bất cứ điều gì, hãy xem xét tích hợp với hệ thống theo dõi lỗi của bạn. Một số công cụ cho phép bạn liên kết một khiếm khuyết hoặc số ID nhiệm vụ trong nhận xét đăng ký với một mục trong công cụ theo dõi. Nếu bạn có tất cả các khiếm khuyết, yêu cầu nâng cao và các tác vụ công việc trong công cụ, bạn có thể cung cấp liên kết theo cách đó. Tất nhiên, điều này đi kèm với nhược điểm của sự phụ thuộc vào các công cụ đó cho dự án.

Có chính xác một trường hợp tôi sẽ làm điều này, cụ thể như là một phần cảnh báo cho các lập trình viên tương lai: "Đừng gọi chức năng foo()trực tiếp ở đây; điều này đã gây ra lỗi # 1234, cụ thể là ...", và sau đó mô tả ngắn về lỗi sau.

Và nếu mã đã thay đổi theo cách không có sự cám dỗ để gọi foo()trực tiếp, hãy xóa nhận xét đó. Nó sẽ chỉ gây khó chịu và làm nổ tung mã.

Đó là một thực tế khủng khiếp. Nó thêm nỗ lực để đạt được một hiệu ứng là sao chép thuần túy; nói cách khác, điều duy nhất mà nó thêm vào chỉ bằng cách sử dụng nhật ký cam kết là khả năng tạo ra sự không nhất quán. Các tệp nguồn của bạn trở nên lộn xộn với số lượng không giới hạn mà bạn không bao giờ nhìn vào.

Ưu điểm duy nhất tôi có thể nhận thấy ở tất cả là bạn có thể xây dựng lại lịch sử nguồn mà không cần truy cập vào kiểm soát phiên bản, ví dụ như khi nghiên cứu bản in. Nhưng rất ít người có đủ năng lực để tuân theo sự phức tạp của phát triển phần mềm, trong khi đồng thời không thể hiểu kiểm soát phiên bản.

Không.

Đó là những gì mọi người đã làm trước khi họ sử dụng một hệ thống kiểm soát phiên bản (tức là khi mã nguồn chỉ là bản sao lưu trong zipfiles).

Đó là, IMHO, một ý tưởng rất tồi. Sau khi sửa đổi số 100, bạn sẽ có 90% ý kiến ​​và 10% mã. Tôi sẽ không coi đó là sạch sẽ và có thể đọc được.

Điểm duy nhất trong điều này tôi thấy là khi bạn phải trao đổi mã giữa các SCC và vì lý do nào đó, bạn không thể chuyển lịch sử giữa hai hệ thống (nhưng ngay cả khi bạn lưu các nhận xét lịch sử theo cách đó, bạn sẽ mất lịch sử tìm khác biệt tốt, vì vậy lưu các ý kiến ​​sẽ chỉ giúp bạn một chút).

Tôi thấy rằng mọi người đều phản đối ý tưởng này và đưa ra một lý do lịch sử (thời đại kiểm soát nguồn trước) về lý do tại sao mọi người thực hiện nó.

Tuy nhiên, trong công ty hiện tại của tôi, các nhà phát triển cơ sở dữ liệu đang theo thông lệ này và họ cũng gắn thẻ số lỗi xung quanh đoạn mã. Đôi khi tôi thấy điều này hữu ích khi bạn thấy một lỗi trong mã và bạn có thể tìm thấy ngay bản sửa lỗi đã giới thiệu vấn đề này. Nếu chúng ta không có thông tin đó trong gói cơ sở dữ liệu của mình thì chắc chắn sẽ không dễ dàng tìm ra nguyên nhân gốc của việc thực hiện đó.

Vâng, nó làm xáo trộn mã, nhưng nó giúp tìm ra lý do tại sao đoạn mã đó ở đó.

Một trong những điểm trong bài kiểm tra Joel là

Bạn có một cơ sở dữ liệu lỗi?

Thông tin như vậy có thể được lưu trong cơ sở dữ liệu lỗi nếu bạn cho rằng chúng quan trọng, nhưng chúng chỉ gây nhiễu trong các bình luận.

Tôi nghĩ rằng bạn có hai vấn đề ở đây. Đầu tiên, tại sao bạn hoàn toàn nên dựa vào diff khi hầu hết các hệ thống cho phép bạn nhập bình luận sửa đổi? Giống như nhận xét mã tốt, bạn khám phá lý do tại sao thay đổi được thực hiện và không chỉ là thay đổi.

Thứ hai, nếu bạn có khả năng này, hãy biến nó thành một thông lệ tốt để đặt tất cả chúng vào cùng một vị trí. Không cần phải xem qua các tập tin để đánh dấu các dòng mã không còn cần thiết. Nhận xét bên trong mã làm việc là có để cho bạn biết lý do tại sao nó được mã hóa theo cách này.

Một khi bạn áp dụng điều này vào thực tế, các thói quen được hình thành làm cho cơ sở mã dễ dàng hoạt động hơn đối với mọi người.

Lỗi liên quan và theo dõi tính năng cùng với lý do tại sao bạn thay đổi tệp này, có thể cho bạn ý tưởng về mức độ bạn cần tìm hiểu sâu về lịch sử và có thể nhìn vào các khác biệt. Tôi đã có một yêu cầu "Thay đổi lại công thức ban đầu." Tôi biết ngay nơi sẽ đi trong lịch sử sửa đổi và chỉ xem xét một hoặc hai khác biệt.

Cá nhân, mã nhận xét trông giống như một công việc đang tiến hành cho một vấn đề đang được giải quyết bằng thử nghiệm và lỗi. Lấy mớ hỗn độn này ra khỏi mã sản xuất. Có thể dễ dàng trượt các dòng mã vào và ra chỉ làm cho nó dễ bị nhầm lẫn hơn.

Nếu bạn không có VCS với thông báo cam kết và không có hệ thống theo dõi lỗi với tùy chọn để bạn để lại nhận xét, thì đó là một tùy chọn chứ không phải tùy chọn tối ưu để theo dõi các thay đổi.
Tốt hơn là có một bảng tính với thông tin đó hoặc nếu bạn đang ở trong một môi trường không có "sự xa xỉ" như vậy, một tệp văn bản nằm ở đâu đó gần nguồn của bạn.
Nhưng tôi thực sự khuyên bạn nên ở trong một môi trường như vậy để bắt đầu xây dựng một trường hợp hướng tới đầu tư vào hệ thống theo dõi lỗi và VCS :)

Hãy ghi nhớ điều này - mã thường dài hơn các công cụ hỗ trợ nó. Nói cách khác, trình theo dõi vấn đề, kiểm soát phiên bản và tất cả các tập lệnh khác sẽ phát triển trong quá trình phát triển. Thông tin bị mất.

Mặc dù tôi đồng ý, sự lộn xộn của tệp rất khó chịu, mở tệp và hiểu lịch sử của nó mà không cần sử dụng các công cụ, luôn rất hữu ích - đặc biệt là nếu tôi đang duy trì mã.

Cá nhân, tôi nghĩ rằng có chỗ cho cả các công cụ và nhật ký mã.

Tôi biết Git không làm điều này và câu trả lời đơn giản là "tại sao trên trái đất sẽ cho nó đi không?"

Đó là một thiết kế ít mô-đun nói chung. Theo giải pháp này, bây giờ các tệp là một số kết hợp giữa nội dung và siêu dữ liệu. Amazon S3 là một ví dụ khác về dịch vụ lưu trữ các tệp không thêm vấn đề trước YAML hoặc tương tự vào các tệp.

Bất kỳ người tiêu dùng nào của tệp đều được yêu cầu xử lý tệp đó thông qua hệ thống kiểm soát phiên bản trước. Đây là khớp nối chặt chẽ, ví dụ IDE yêu thích của bạn sẽ bị hỏng nếu nó không hỗ trợ VCS của bạn.

Không, nó không phải là một thực hành tốt để theo dõi sửa lỗi của bạn như nhận xét trong mã. Điều này chỉ tạo ra sự lộn xộn.

Tôi cũng sẽ nói tương tự cho thông điệp bản quyền mà bạn đề cập. Nếu không có ai bên ngoài công ty của bạn sẽ thấy mã này, không có lý do gì để đưa vào thông báo bản quyền.

Nếu bạn đang sử dụng phần mềm theo dõi phiên bản ( Git , SVN , v.v.), thì bạn nên đưa các ghi chú đó vào tin nhắn cam kết của mình. Không ai muốn tìm hiểu các tiêu đề của mỗi tệp mã để tạo ghi chú phát hành hoặc xem tổng quan về những thay đổi đã được thực hiện. Tất cả các nhật ký thay đổi này phải được lưu trữ cùng nhau, trong lịch sử theo dõi phiên bản, theo dõi lỗi của bạn hoặc cả hai.

Nếu bạn đang tìm kiếm một bài đọc tốt về chủ đề này, tôi khuyên bạn nên sử dụng chương bốn của Clean Code .

Tôi nghĩ rằng có những yếu tố khác cho cuộc thảo luận này thường bị lãng quên nhưng là những trường hợp mà một số nhận xét sửa đổi được gửi đến một nhóm.

Khi làm việc trong môi trường nhóm với cơ sở mã được chia sẻ và trong đó một số thành viên trong nhóm có khả năng làm việc trong cùng một lĩnh vực mã, đặt một nhận xét sửa đổi ngắn trong phạm vi (phương thức hoặc lớp) chính xác cho thấy một thay đổi có thể rất hữu ích cho nhanh chóng giải quyết xung đột hợp nhất hoặc checkin.

Tương tự như vậy, khi làm việc trong môi trường có nhiều nhánh (tính năng) tham gia, giúp người thứ ba (chủ xây dựng) dễ dàng hơn trong việc xác định những việc cần làm để giải quyết xung đột tiềm ẩn.

Bất cứ khi nào bạn phải rời khỏi IDE và hỏi ai đó tại sao họ thay đổi điều gì đó, điều đó sẽ làm gián đoạn năng suất của cả hai thành viên trong nhóm. Một ghi chú nhanh trong phạm vi chính xác có thể giúp giảm bớt hoặc loại bỏ hầu hết sự gián đoạn này.

Bất kỳ thông tin lỗi nào liên quan trực tiếp đến một đoạn mã, sẽ trở nên không liên quan khi tính toàn vẹn của toàn bộ thay đổi được sửa đổi bằng cách sửa liên tiếp.

Nó được sử dụng phổ biến để thêm thông tin trong tóm tắt chức năng khi chúng ta phải dựa vào các công cụ bên ngoài (giả sử javadocs) để tạo ghi chú phát hành từ mã. Nó chủ yếu là vô dụng hoặc dư thừa với các công cụ kiểm soát phiên bản hiện đại.

Nó chỉ có thể có ý nghĩa như là một nhận xét trong một đoạn mã rất mô-đun, nếu người ta phải dùng đến một mã hóa tối nghĩa hoặc không rõ ràng mà các nhà phát triển trong tương lai sẽ bị cám dỗ thay đổi - không biết lý do đằng sau nó - như trong một cách giải quyết lỗi thư viện / thiếu sót.

Tôi chắc chắn sẽ không đưa thông tin đó vào đầu tập tin - thường thì những thứ đó thuộc về hệ thống bán vé.

Tuy nhiên, có một số trường hợp tham chiếu vào hệ thống vé và / hoặc tài liệu khác có ý nghĩa. Ví dụ, nếu có một lời giải thích dài về thiết kế, hoặc mô tả các lựa chọn thay thế. Hoặc thông tin làm thế nào để kiểm tra mọi thứ, hoặc giải thích tại sao nó được thực hiện chính xác theo cách đó. Nếu đó là ngắn, nó thuộc về chính tập tin; nếu nó dài và / hoặc là về một bức tranh lớn hơn, có lẽ bạn sẽ muốn đặt nó ở một nơi khác và tham khảo nó.

Dự án tôi hiện đang được giao tại nơi làm việc có loại danh sách số lỗi này ở đầu mỗi tệp; tuy nhiên, không ai trong số các nhà phát triển vẫn còn trong dự án nối thêm nó nữa. Hầu hết trong số họ nghĩ rằng đó là một sự lãng phí không gian vô ích, vì nó kém hơn nhiều so với việc theo dõi lỗi cam kết với một tệp bằng hệ thống kiểm soát phiên bản của chúng tôi.

Trong một số tệp quan trọng nhất định đã trải qua nhiều sửa chữa và cải tiến, các danh sách này đã trở nên quá lớn, bạn phải cuộn qua chúng để lấy mã. Khi gre các danh sách này có thể dẫn đến một số tích cực sai như một tiêu đề lỗi ngắn hoặc mô tả ngắn được liệt kê với mỗi danh sách.

Nói tóm lại, những danh sách này tốt nhất là vô dụng và tệ nhất là một sự lãng phí không gian lớn, hỗn loạn khiến cho mã khó tìm kiếm và định vị hơn.