Cách tiếp cận tốt nhất cho ý kiến ​​mã nội tuyến là gì?

Chúng tôi đang thực hiện một số tái cấu trúc cho một cơ sở mã di sản 20 năm tuổi và tôi đang thảo luận với đồng nghiệp của mình về định dạng nhận xét trong mã (xin vui lòng, java).

Không có định dạng mặc định cho các bình luận, nhưng trong hầu hết các trường hợp, mọi người làm điều gì đó như thế này trong bình luận:

// date (year, year-month, yyyy-mm-dd, dd/mm/yyyy), (author id, author name, author nickname) and comment

định dạng đề xuất cho các bình luận trong tương lai và quá khứ mà tôi muốn là:

// {yyyy-mm-dd}, unique_author_company_id, comment

Đồng nghiệp của tôi nói rằng chúng tôi chỉ cần nhận xét và phải định dạng lại tất cả các nhận xét trong quá khứ và tương lai theo định dạng này:

// comment

Lập luận của tôi:

• Tôi nói vì lý do bảo trì, điều quan trọng là phải biết khi nào và ai đã thay đổi (ngay cả thông tin này cũng có trong SCM).
• Mã đang sống và vì lý do đó có một lịch sử.
• Bởi vì không có ngày thay đổi, không thể biết khi nào một thay đổi được đưa ra mà không mở công cụ SCM và tìm kiếm trong lịch sử đối tượng dài.
• bởi vì tác giả rất quan trọng, một sự thay đổi của tác giả đáng tin cậy hơn sự thay đổi của tác giả
• Lý do nhanh nhẹn, không cần mở và điều hướng thông qua công cụ SCM
• mọi người sẽ sợ thay đổi thứ gì đó mà ai đó đã làm 15 năm trước, hơn là thứ được tạo ra hoặc thay đổi gần đây.
• Vân vân.

Lập luận của đồng nghiệp của tôi:

• Lịch sử là trong SCM
• Các nhà phát triển không được biết về lịch sử của mã trực tiếp trong mã
• Các gói được dài 15k dòng và nhận xét không có cấu trúc làm cho các gói này khó hiểu hơn

Bạn nghĩ gì là cách tiếp cận tốt nhất? Hay bạn có một cách tiếp cận tốt hơn để giải quyết vấn đề này?

Nhận xét chung

Tôi là một người tin tưởng tuyệt vời trong các ý kiến ​​là tại sao (không phải như thế nào) . Khi bạn bắt đầu thêm nhận xét về cách bạn rơi vào vấn đề không có gì bắt buộc các bình luận đó được duy trì liên quan đến mã ( lý do tại sao thường sẽ không thay đổi (lý do tại sao có thể được tăng cường theo thời gian)).

Theo cùng một cách date / AuthorInfo không giúp bạn đạt được bất cứ điều gì về lý do tại sao mã được thực hiện theo cách này; giống như cách nó có thể thoái hóa theo thời gian bởi vì không có sự thực thi bởi bất kỳ công cụ nào. Ngoài ra, thông tin tương tự đã được lưu trữ trong hệ thống kiểm soát nguồn (vì vậy bạn đang nhân đôi nỗ lực (nhưng theo cách ít tin cậy hơn)).

Đi qua các cuộc tranh luận:

Tôi nói vì lý do bảo trì, điều quan trọng là phải biết khi nào và ai đã thay đổi (ngay cả thông tin này cũng có trong SCM).

Tại sao. Cả hai điều này đều không quan trọng đối với tôi trong việc duy trì mã. Nếu bạn cần nói chuyện với tác giả, việc tìm thông tin này từ kiểm soát nguồn tương đối đơn giản.

Mã có cuộc sống vì lý do đó đã có một lịch sử.

Lịch sử được lưu trữ trong kiểm soát nguồn.
Bạn cũng tin rằng bình luận được viết bởi người đó. Howý kiến ​​có xu hướng xuống cấp theo thời gian vì vậy loại lịch sử này trở nên không đáng tin cậy. Mặt khác, các hệ thống kiểm soát nguồn sẽ duy trì một lịch sử rất chính xác và bạn có thể thấy chính xác khi các bình luận được thêm / xóa.

Bởi vì không có ngày thay đổi, không thể biết khi nào một thay đổi được đưa ra mà không mở công cụ SCM và tìm kiếm trong lịch sử đối tượng dài.

Nếu bạn tin tưởng dữ liệu trong một bình luận.
Một trong những vấn đề với loại điều này là các bình luận trở nên không chính xác liên quan đến mã. Quay lại công cụ chính xác cho công việc. Hệ thống kiểm soát nguồn sẽ thực hiện việc này một cách chính xác mà không cần sự can thiệp từ người dùng. Nếu hệ thống kiểm soát nguồn của bạn là một nỗi đau thì có lẽ bạn cần phải học cách sử dụng nó một cách phù hợp hơn (vì chức năng đó thường dễ dàng) hoặc nếu không hỗ trợ thì hãy tìm một hệ thống kiểm soát nguồn tốt hơn.

bởi vì tác giả rất quan trọng, một sự thay đổi của tác giả là đáng tin cậy hơn là một sự thay đổi của tác giả

Tất cả các tác giả (ngoài chính bạn) đều đáng tin cậy như nhau.

Lý do nhanh nhẹn, không cần mở điều hướng công cụ SCM

Nếu công cụ kiểm soát nguồn của bạn là gánh nặng mà bạn khô héo khi sử dụng nó không chính xác hoặc (rất có thể) bạn đang sử dụng bộ công cụ sai để truy cập hệ thống kiểm soát nguồn.

mọi người sẽ sợ thay đổi một cái gì đó mà ai đó đã làm 15 năm trước, hơn là đôi khi nó được thực hiện ...

Nếu mã đã tồn tại 15 năm thì có nhiều khả năng vững chắc hơn thì mã chỉ tồn tại được 6 tháng mà không cần xem xét. Mã ổn định có xu hướng ổn định, mã lỗi có xu hướng phức tạp hơn theo thời gian (vì lý do là lỗi là vấn đề không đơn giản như suy nghĩ ban đầu).

Thậm chí nhiều lý do để sử dụng kiểm soát nguồn để có được thông tin.

Lịch sử là trong SCM

Đúng. Lý do tốt nhất chưa.

Các nhà phát triển không được biết về lịch sử của mã trực tiếp trong mã

Nếu tôi thực sự cần thông tin này, tôi sẽ tra cứu nó trong kiểm soát nguồn.
Nếu không thì nó không liên quan.

Các gói được dài 15k và nhận xét không có cấu trúc, gói này khó hiểu hơn

Nhận xét nên là một mô tả về lý do tại sao bạn đang làm một cái gì đó.
Nhận xét KHÔNG nên mô tả cách thức hoạt động của mã (trừ khi thuật toán không rõ ràng).

Tôi rất ủng hộ đồng nghiệp của bạn. Dù sao bạn cũng sẽ không nhận được nếu không nhìn vào SCM nếu bạn muốn hiểu tại sao có gì đó bị thay đổi trừ khi bạn giữ mã cũ trong một bình luận.

Nếu mã quá phức tạp để có thể hiểu được mà không viết hàng tấn bình luận, tôi khuyên bạn nên đầu tư năng lượng cho bạn để tái cấu trúc để làm cho mã có thể đọc / duy trì được mà không cần quá nhiều bình luận.

Rốt cuộc, bạn thuê lập trình viên, không phải người kể chuyện ;-)