Bảo trì mã: Để thêm nhận xét trong mã hoặc chỉ để lại cho kiểm soát phiên bản?

Chúng tôi đã được yêu cầu thêm nhận xét với thẻ bắt đầu, thẻ kết thúc, mô tả, giải pháp, v.v. cho mỗi thay đổi mà chúng tôi thực hiện đối với mã như là một phần của việc sửa lỗi / thực hiện CR.

Mối quan tâm của tôi là, điều này có cung cấp bất kỳ giá trị gia tăng? Như vậy, chúng ta có tất cả các chi tiết trong lịch sử kiểm soát Phiên bản, điều này sẽ giúp chúng ta theo dõi từng thay đổi?

Nhưng khách hàng tiềm năng của tôi đang khăng khăng đòi có những bình luận là một thực hành lập trình "tốt". Một trong những tranh luận của họ là khi CR phải được loại bỏ / thay đổi, sẽ rất cồng kềnh nếu không có bình luận.

Xem xét rằng các thay đổi sẽ chủ yếu ở giữa mã, nó có thực sự giúp thêm ý kiến ​​cho mỗi thay đổi chúng tôi thực hiện không? Chúng ta không nên để nó cho kiểm soát phiên bản?

Bạn hoàn toàn đúng. Theo dõi thay đổi là công việc cho hệ thống kiểm soát phiên bản của bạn. Mỗi khi bạn thực hiện một cam kết, bạn nên viết một thông điệp cam kết giải thích những gì đã được thực hiện và tham khảo hệ thống theo dõi lỗi của bạn nếu đây là một sửa lỗi. Đặt một nhận xét trong mã nói

// begin fix for bug XXXXX on 10/9/2012
...
// end fix for bug XXXXX

mỗi khi bạn sửa một lỗi sẽ nhanh chóng khiến mã của bạn không thể đọc được và không thể nhận ra. Nó cũng sẽ dẫn đến việc sao chép cùng một thông tin ở hai nơi, điều này sẽ làm cho tình trạng lộn xộn trở nên tồi tệ hơn.

Nhận xét không nên được sử dụng để theo dõi lỗi và họ cũng không nên mô tả những gì mã của bạn đang làm. Họ nên giải thích lý do tại sao bạn làm X, hoặc tại sao bạn làm X theo cách đặc biệt này. Nếu bạn cảm thấy cần phải viết bình luận giải thích một khối mã đang làm gì, thì đó là mùi mã cho biết bạn nên cấu trúc lại khối này thành một hàm có tên mô tả.

Vì vậy, thay vì

// fixed bug XXXXX on 10/9/2012

bạn có thể có một bình luận nói rằng

// doing X, because otherwise Y will break.

hoặc là

// doing X, because doing Y is 10 times slower.

Sử dụng công cụ tốt nhất cho công việc. Hệ thống kiểm soát phiên bản của bạn phải là công cụ tốt nhất để ghi lại khi lỗi và CR được tạo: nó tự động ghi lại ngày và ai đã thực hiện thay đổi; nó không bao giờ quên để thêm một tin nhắn (nếu bạn đã cấu hình nó để yêu cầu tin nhắn cam kết); nó không bao giờ chú thích sai dòng mã hoặc vô tình xóa một bình luận. Và nếu hệ thống kiểm soát phiên bản của bạn đã hoạt động tốt hơn bình luận của bạn, thì thật ngu ngốc khi sao chép công việc bằng cách thêm nhận xét.

Khả năng đọc mã nguồn là tối quan trọng. Một codebase lộn xộn với các bình luận cung cấp toàn bộ lịch sử của mọi lỗi và CR được tạo ra sẽ không dễ đọc chút nào.

Nhưng đừng bỏ qua các bình luận hoàn toàn: Các bình luận tốt (không phải là tài liệu rõ ràng mỗi khi bắt đầu / dừng / mô tả / giải pháp của mọi lỗi và CR) nâng cao khả năng đọc của mã. Ví dụ, đối với một đoạn mã phức tạp hoặc không rõ ràng mà bạn thêm vào để sửa lỗi, một bình luận của biểu mẫu // fix ISSUE#413cho mọi người biết nơi tìm thêm thông tin trong trình theo dõi vấn đề của bạn là một ý tưởng tuyệt vời.

Nhận xét trong mã là về những gì mã là tại thời điểm đó. Chụp ảnh nhanh tại bất kỳ thời điểm nào không nên tham khảo các phiên bản cũ (hoặc tệ hơn, tương lai) của mã.

Nhận xét trong VCS là về cách mã đã thay đổi. Họ nên đọc như một câu chuyện về sự phát triển.

Bây giờ, mọi thay đổi nên bao gồm ý kiến? trong hầu hết các trường hợp, có. Ngoại lệ duy nhất tôi tưởng tượng là khi hành vi dự kiến ​​đã được ghi lại nhưng không phải là những gì bạn có, vì một lỗi. Sửa nó làm cho các bình luận hiện tại chính xác hơn, vì vậy chúng không phải thay đổi. Bản thân lỗi phải được ghi lại trong lịch sử vé và nhận xét cam kết, nhưng chỉ trong mã nếu mã trông lạ. Trong trường hợp đó, một // make sure <bad thing> doesn't happennên là đủ.

Một loại bình luận tôi thực sự đánh giá cao là:

// Điều này được thực hiện cho Quy tắc kinh doanh 5 của Đề xuất 2

hoặc bất cứ cái quái gì bạn sử dụng để thu thập các yêu cầu của bạn.

Điều này có hai ưu điểm, một là nó cho phép bạn tìm ra lý do bạn triển khai một thuật toán nhất định mà không cần tìm kiếm và một lý do khác là nó sẽ giúp bạn giao tiếp với các kỹ sư không phải phần mềm làm việc trên / tạo các tài liệu yêu cầu.

Điều này có thể không giúp được với các nhóm nhỏ hơn nhưng nếu bạn có các nhà phân tích phát triển các yêu cầu của bạn, nó có thể là vô giá.

Khách hàng tiềm năng của bạn là đúng khi họ nói rằng bình luận là một thực hành lập trình tốt, tuy nhiên vẫn có trường hợp ngoại lệ. Thêm một bình luận cho mọi thay đổi mà bạn thực hiện là một trong số đó. Và bạn đã đúng khi nói rằng điều này nên thuộc về hệ thống kiểm soát phiên bản. Nếu bạn phải giữ những bình luận này ở một nơi duy nhất, thì VCS là con đường để đi. Nhận xét trong mã nguồn có xu hướng trở nên cũ và không rõ ràng. Không có bình luận nào tốt hơn nhiều so với bình luận xấu. Điều bạn không muốn là có ý kiến ​​ở cả hai nơi (trong mã và VCS) không đồng bộ. Mục tiêu là giữ cho mọi thứ KHÔ bằng cách có một nguồn sự thật duy nhất cho các thay đổi đối với mã.

Ngoài những gì người khác đã nói, hãy xem xét những gì sẽ xảy ra nếu một thay đổi có hiệu ứng gợn trên toàn hệ thống. Giả sử bạn cấu trúc lại một phần của giao diện cốt lõi trong quá trình thực hiện yêu cầu thay đổi - loại thay đổi đó có thể dễ dàng chạm vào một tỷ lệ lớn các tệp mã nguồn trong bất kỳ phần mềm không tầm thường nào với số tiền thay đổi nhỏ (lớp hoặc thay đổi tên phương thức). Bạn có phải đi qua từng tệp được chạm bởi một thao tác như vậy để chú thích thủ công nó với các nhận xét như vậy, thay vì dựa vào VCS tự động thực hiện tất cả không? Trong một trường hợp, bạn đang xem xét ít hơn một công việc năm phút với bất kỳ công cụ tái cấu trúc tử tế nào theo sau là biên dịch lại để đảm bảo không có gì phá vỡ công trình, trong khi công việc kia có thể dễ dàng bắt đầu công việc trong một ngày. Vì lợi ích cụ thể nào?

Cũng xem xét những gì xảy ra khi bạn di chuyển các phần của mã xung quanh. Một trong những nhà phát triển cơ sở dữ liệu mà tôi làm việc cùng là phần lớn "mỗi dòng SQL nên được chú thích với bản sửa đổi đã được thay đổi và chúng tôi sẽ thực hiện lịch sử sửa đổi riêng cho từng tệp vì sau đó dễ thấy hơn ai thay đổi cái gì khi nào và tại sao ". Điều đó hoạt động khá ổn khi thay đổi làtheo thứ tự thay đổi dòng đơn. Nó cũng không hoạt động tốt khi, như tôi đã làm gần đây để khắc phục vấn đề hiệu năng nghiêm trọng, bạn thoát ra các phần của truy vấn lớn hơn giới thiệu các bảng tạm thời, sau đó thay đổi thứ tự của một số truy vấn để phù hợp hơn với luồng mã mới. Cấp, khác biệt so với phiên bản trước phần lớn là vô nghĩa vì nó cho biết khoảng hai phần ba tệp đã thay đổi, nhưng nhận xét đăng ký cũng giống như "tổ chức lại chính để khắc phục các vấn đề về hiệu suất". Vào thời điểm bạn nhìn thủ công hai phiên bản, khá rõ ràng rằng các phần lớn thực sự giống nhau, chỉ di chuyển xung quanh. (Và phải mất thủ tục được lưu trữ trong câu hỏi từ thường xuyên mất hơn nửa phút để thực thi, đến vài giây. Đến lúc đó,

Với rất ít ngoại lệ, theo dõi thay đổi và tham chiếu vấn đề là công việc của VCS, IMNSHO.

Tôi thường tuân theo quy tắc này: nếu thay đổi là rõ ràng và mã kết quả không đặt ra câu hỏi, không hoàn nguyên hoặc thay đổi đáng kể bất kỳ hành vi nào trước đây theo cách đáng kể - sau đó để lại cho VCS để theo dõi số lỗi và thông tin thay đổi khác.

Tuy nhiên, nếu có sự thay đổi không rõ ràng, điều đó sẽ thay đổi logic - đặc biệt là thay đổi đáng kể logic được thực hiện bởi người khác theo cách không rõ ràng - có thể rất có ích khi thêm một cái gì đó như "thay đổi này là để làm điều này và đó là do lỗi # 42742 ". Theo cách này khi ai đó nhìn vào mã và tự hỏi "tại sao lại ở đây? Điều này có vẻ kỳ lạ", anh ta có một số hướng dẫn ngay lập tức và không phải điều tra thông qua VCS. Điều này cũng ngăn chặn các tình huống nơi mọi người phá vỡ các thay đổi của người khác vì họ đã quen với trạng thái cũ của mã nhưng không nhận thấy nó đã bị thay đổi kể từ đó.

Nhận xét liên quan đến kiểm soát phiên bản không thuộc về tệp nguồn. Họ chỉ thêm lộn xộn. Vì chúng có thể được yêu cầu đặt ở cùng một vị trí (như khối bình luận ở đầu tệp), chúng sẽ gây ra xung đột phiền toái chỉ nhận xét khi các nhánh song song được hợp nhất.

Bất kỳ thông tin theo dõi nào có thể được rút ra khỏi kiểm soát phiên bản không nên được sao chép trong phần thân của mã. Điều đó áp dụng cho những ý tưởng ngớ ngẩn như các từ khóa thanh toán RCS như $Log$và ilk của nó.

Nếu mã bao giờ đi ra ngoài phạm vi của hệ thống kiểm soát phiên bản, thì dòng ý kiến ​​về lịch sử của nó sẽ mất bối cảnh và do đó phần lớn giá trị của nó. Để hiểu đúng về mô tả của thay đổi, chúng tôi cần quyền truy cập vào bản sửa đổi, vì vậy chúng tôi có thể xem khác với phiên bản trước.

Một số tệp cũ trong nhân Linux có các khối nhận xét lịch sử lớn. Những ngày đó trở lại khi không có hệ thống kiểm soát phiên bản, chỉ có tarball và các bản vá.

Nhận xét trong mã phải tối thiểu và chính xác. Thêm thông tin khiếm khuyết / thay đổi không có giá trị. Bạn nên sử dụng kiểm soát phiên bản cho nó. Một số thời gian Kiểm soát phiên bản cung cấp một cách thay đổi tốt hơn một chút - Chúng tôi sử dụng ClearCase UCM; Các hoạt động UCM được tạo dựa trên số lượng lỗi, thay đổi khu vực, v.v. (ví dụ: defect29844_change_sql_to_handle_null).

Bình luận chi tiết được ưa thích trong ý kiến ​​check-in.

Tôi thích bao gồm cung cấp chi tiết về thông tin mặt đất, chi tiết về giải pháp KHÔNG được triển khai do một số tác dụng phụ.

Lập trình viên Pramagic và CleanCode dẫn đến hướng dẫn sau

Giữ kiến ​​thức cấp thấp trong mã, nơi nó thuộc về và bảo lưu ý kiến ​​cho các giải thích cấp cao khác.