Có một điểm để bao gồm một bản ghi nhật ký thay đổi của Mt trong mỗi tệp mã khi bạn đang sử dụng kiểm soát phiên bản không?

Tôi có ấn tượng rằng một hệ thống kiểm soát phiên bản đã loại bỏ sự cần thiết phải "thay đổi nhật ký" được dán ở mọi nơi trong mã. Tôi thường thấy việc tiếp tục sử dụng nhật ký thay đổi, bao gồm các khối lớn khi bắt đầu các thủ tục được lưu trữ với một phần lớn bị chặn để thay đổi tệp và xả rác mã với những thứ như:

// 2011-06-14 (John Smith) Change XYZ to ABC to fix Bug #999

và:

// 2009-95-12 (Bob Jones) Extracted this code to Class Foo 
// <commented-out code here>

Lý do cho điều này, như đã được giải thích với tôi, là vì mất quá nhiều thời gian để sàng lọc nhật ký VCS của chúng tôi để cố gắng tìm ra ai đã thay đổi cái gì và tại sao, trong khi có nó trong tệp mã, ở đầu hoặc gần có liên quan thay đổi, giúp dễ dàng nhận ra ai đã thay đổi cái gì và khi nào. Trong khi tôi thấy vấn đề đó, có vẻ như là dư thừa và chỉ là một loại cú đánh "Ơ chúng tôi không thực sự hiểu cách sử dụng VCS của chúng tôi đúng cách, vì vậy chúng tôi sẽ không bận tâm đến những thứ đó."

Bạn nghĩ sao? Bạn có sử dụng cả bình luận và nhật ký? Chỉ là nhật ký? Bạn có thấy rằng việc viết mã dễ dàng hơn khi bạn có thể thấy phía trên một khối mã mà John Smith đã thay đổi phương pháp để kiểm tra XYZ một tuần trước, thay vì phải tìm kiếm thông qua nhật ký và so sánh các tệp mã trong công cụ Diff?

EDIT: Sử dụng SVN, nhưng về cơ bản chỉ là một kho lưu trữ. Không có chi nhánh, không hợp nhất, không có gì ngoại trừ log + lưu trữ.

Tôi có xu hướng xóa bình luận trong mã. Và bằng cách xóa, ý tôi là, với định kiến . Trừ khi một bình luận giải thích tại sao một chức năng cụ thể làm một cái gì đó, nó sẽ biến mất. Tạm biệt. Đừng vượt qua đi.

Vì vậy, nó không làm bạn ngạc nhiên rằng tôi cũng sẽ xóa những thay đổi đó, vì lý do rất giống nhau.

Vấn đề với mã nhận xét và nhận xét đọc như sách là bạn không thực sự biết nó có liên quan như thế nào và nó mang lại cho bạn cảm giác hiểu sai về những gì mã thực sự làm.

Có vẻ như nhóm của bạn không có công cụ tốt xung quanh hệ thống kiểm soát Phiên bản của bạn. Vì bạn nói rằng bạn đang sử dụng Subversion, tôi muốn chỉ ra rằng có rất nhiều công cụ sẽ giúp bạn quản lý kho lưu trữ lật đổ của bạn. Từ khả năng điều hướng nguồn của bạn thông qua web, đến việc liên kết các thay đổi của bạn với các lỗi cụ thể, bạn có thể làm rất nhiều việc để giảm thiểu sự cần thiết của những 'thay đổi' này.

Tôi đã có rất nhiều người bình luận và nói rằng có lẽ tôi có lỗi khi xóa bình luận. Phần lớn mã tôi đã thấy được nhận xét là mã xấu và các nhận xét chỉ làm cho vấn đề trở nên khó hiểu. Trên thực tế, nếu tôi từng nhận xét mã, bạn có thể yên tâm rằng tôi đang yêu cầu sự tha thứ từ lập trình viên bảo trì vì tôi tương đối chắc chắn họ sẽ muốn giết tôi.

Nhưng e rằng bạn nghĩ rằng tôi nên xóa các bình luận trong trò đùa, bài nộp WTF hàng ngày này (từ một cơ sở mã mà tôi đã làm việc) minh họa quan điểm của tôi một cách hoàn hảo:

/// The GaidenCommand is a specialized Command for use by the
/// CommandManager.
///
/// Note, the word "gaiden" is Japanese and means "side story",
/// see "http://en.wikipedia.org/wiki/Gaiden".
/// Why did I call this "GaidenCommand"? Because it's very similar to
/// a regular Command, but it serves the CommandManager in a different
/// way, and it is not the same as a regular "Command". Also
/// "CommandManagerCommand" is far too long to write. I also toyed with
/// calling this the "AlephCommand", Aleph being a silent Hebrew
/// letter, but Gaiden sounded better.

Ồ ... Những câu chuyện tôi có thể kể cho bạn về cơ sở mã hóa đó, và tôi sẽ, ngoại trừ việc nó vẫn được sử dụng bởi một trong những tổ chức chính phủ lớn nhất xung quanh.

Những "nhật ký thay đổi" được nhúng trong mã đặc biệt khó hiểu. Chúng chỉ hiển thị như một sự khác biệt khác khi bạn chỉnh sửa khác nhau, và một điều mà bạn không thực sự quan tâm. Tin tưởng vào VCS của bạn - hầu hết đều có tính năng "đổ lỗi" sẽ cho bạn thấy rất nhanh những người đã thay đổi những gì.

Tất nhiên, điều thực sự khủng khiếp là tính năng của VCS "thời xưa" nơi bạn có thể có nhật ký VCS thực tế được nhúng trong các tệp nguồn. Thực hiện sáp nhập gần như không thể.

Tôi có một tệp ChangeLog duy nhất cho mỗi dự án được tự động điền bởi các thông điệp cam kết nhất định.

Chúng tôi không nhúng các bình luận ChangeLog. Nếu chúng tôi làm tôi sẽ loại bỏ chúng và "nói chuyện" với người thêm chúng. Tôi nghĩ rằng họ là biểu hiện của việc không hiểu các công cụ bạn sử dụng, đặc biệt là các vcs.

Chúng tôi có một định dạng cho các thông điệp cam kết giúp dễ dàng grep các bản ghi. Chúng tôi cũng không cho phép các tin nhắn cam kết vô dụng hoặc mơ hồ.

Cá nhân tôi ghê tởm nhật ký thay đổi trong tập tin nguồn mã. Đối với tôi chỉ cảm thấy như nó vi phạm một nguyên tắc của công nghệ phần mềm ở chỗ mọi thay đổi tôi thực hiện phải được thực hiện ở nhiều nơi. Rất nhiều lần thông tin nhật ký thay đổi là hoàn toàn vô dụng và không quan trọng. Theo ý kiến ​​khiêm tốn của tôi, các thay đổi đối với phần mềm nên được ghi lại khi bạn kiểm tra mã.

Nhưng tôi biết gì ...

Tôi nghĩ rằng nếu có một sự khăng khăng khi thực hiện việc giữ nhật ký thay đổi trong mã nguồn thì nhật ký thay đổi sẽ được giới hạn ở những thay đổi ảnh hưởng đến giao diện / API xung của lớp. Nếu bạn đang thực hiện các thay đổi trong lớp sẽ không phá vỡ bất kỳ mã nào sử dụng nó, việc ghi lại những thay đổi này trong nhật ký thay đổi chỉ là sự lộn xộn theo quan điểm của tôi. Tuy nhiên, tôi có thể thấy làm thế nào đôi khi có thể tiện dụng để có thể kiểm tra phần trên của tệp mã nguồn để tìm tài liệu về bất kỳ thay đổi nào có thể làm hỏng bất cứ điều gì cho bất kỳ ai khác. Chỉ là một bản tóm tắt về cách thay đổi có thể ảnh hưởng đến API và tại sao thay đổi được thực hiện.

Mặt khác, cửa hàng của tôi chủ yếu thực hiện công cụ C # và chúng tôi luôn sử dụng các nhận xét XML nội tuyến để ghi lại API của mình, vì vậy việc đọc tài liệu về các thay đổi API công khai ít nhiều đơn giản như sử dụng intellisense.

Tôi nghĩ rằng việc nhấn mạnh vào nhật ký thay đổi trong tệp nguồn chỉ là thêm ma sát không cần thiết vào máy và đánh bại một trong những mục đích của việc triển khai hệ thống kiểm soát phiên bản ngay từ đầu.

Công ty cuối cùng tôi làm việc có phần mềm có 17 năm lịch sử, phát triển và cập nhật hàng năm đằng sau nó. Không phải tất cả các lần di chuyển từ một hệ thống kiểm soát phiên bản sang phiên bản tiếp theo sẽ lưu giữ các bình luận hoặc ghi chú đăng ký. Tất cả các nhà phát triển trong những năm đó cũng không duy trì bất kỳ sự thống nhất nào với các nhận xét / ghi chú đăng ký.

Với các bình luận trong mã nguồn, lịch sử khảo cổ về các thay đổi được lưu giữ dưới dạng ghi chú, không nhận xét mã. Và, vâng, họ vẫn đang vận chuyển mã VB6.

Kiểm soát phiên bản có thể thay thế những nhận xét nhật ký thay đổi trong mã nếu các nhà phát triển trong nhóm của bạn đang sử dụng đúng.

Nếu nhóm của bạn không thêm nhận xét khi đăng ký hoặc để lại nhận xét không có ích, thì sẽ rất khó để tìm thấy thông tin bạn đang tìm kiếm trong tương lai.

Tại công ty hiện tại của tôi, chúng tôi được yêu cầu gửi bình luận với mỗi lần đăng ký. Không chỉ vậy, chúng tôi dự kiến ​​sẽ đính kèm mỗi lần đăng ký với một vé ở Jira. Khi bạn tìm kiếm trong Jira trong tương lai, bạn có thể thấy mọi tệp đã được kiểm tra và khi nào cho vấn đề đó cùng với nhận xét còn lại. Nó khá tiện dụng.

Về cơ bản, kiểm soát phiên bản chỉ là một công cụ, đó là cách nhóm của bạn sử dụng công cụ đó sẽ cung cấp những lợi thế mà bạn đang tìm kiếm. Mọi người trong nhóm cần đồng ý với cách họ sẽ sử dụng nó để cung cấp theo dõi sửa lỗi tốt nhất cũng như sửa đổi mã sạch.

Đây là một phần còn sót lại từ những ngày mà nhật ký VCS khó hiểu và các hệ thống VCS rất khó xử lý (Tôi nhớ những ngày đó, ở đâu đó vào phần cuối của thập niên 80).

Sự nghi ngờ của bạn là hoàn toàn chính xác, những bình luận này gây trở ngại nhiều hơn là giúp đỡ và bất kỳ VCS hiện đại nào cũng sẽ cho phép bạn tìm thấy chính xác những gì bạn đang tìm kiếm. Tất nhiên, bạn (và đồng nghiệp của bạn) sẽ phải chi tiêu khoảng. 30-60 phút học cách lái tất cả các tính năng này (mà tôi nghi ngờ, thực sự là lý do tại sao những bình luận này vẫn còn đó).

Tôi giữ nó (gần như) với George. Nhận xét trong mã chỉ thực sự hợp lý nếu chúng giải thích điều gì đó không thể nhìn thấy ngay lập tức trong chính mã. Và điều đó chỉ xảy ra hiếm khi trong mã tốt. Nếu bạn có nhu cầu có nhiều bình luận trong mã của mình, đó là một mùi của riêng nó và nó sẽ hét lên "tái cấu trúc tôi!".

Chúng tôi vẫn đưa chúng vào nguồn thủ tục được lưu trữ bởi vì đó là cách chúng tôi có thể biết chính xác phiên bản nào được áp dụng tại máy khách. Phần còn lại của ứng dụng được phân phối biên dịch, vì vậy chúng tôi có số phiên bản mô-đun liên kết lại với nguồn, nhưng SP được phân phối dưới dạng nguồn cho các máy khách để biên dịch trong cơ sở dữ liệu cục bộ.

Mã PowerBuilder kế thừa của chúng tôi vẫn sử dụng chúng, nhưng tôi nghĩ đó chỉ là một yếu tố thoải mái cho một số peeps. Điều đó cũng được biên dịch để phân phối, vì vậy (IMO họ oughtta) sử dụng lịch sử VCS friggin.

Nếu bạn đang sử dụng SVN, làm điều đó là một sự lãng phí thời gian và hoàn toàn vô dụng.

SVN có chức năng đổ lỗi. Điều đó sẽ cho bạn biết chính xác ai đã thực hiện mọi dòng trong một tệp nhất định và khi nào.

Thay đổi nhận xét nhật ký đặc biệt hữu ích trong mã khi chúng giúp nhà phát triển tiếp theo đặt câu hỏi tốt hơn về các yêu cầu mới. Ví dụ, khi nhà phát triển thấy một bình luận, Fred đã đưa ra trường Foo cần 6 tháng trước để đáp ứng một số yêu cầu, nhà phát triển đó biết rằng họ cần phải hỏi một số câu hỏi trước khi thực hiện yêu cầu mới nhất để đưa Foo tùy chọn. Khi bạn đang làm việc với các hệ thống phức tạp, các bên liên quan khác nhau có thể có các ưu tiên khác nhau và mong muốn khác nhau. Thay đổi nhận xét nhật ký có thể rất hữu ích cho việc ghi lại những sự đánh đổi này đã được thực hiện để tránh các vấn đề trong tương lai.

Bây giờ, nếu mọi nhà phát triển kiểm tra lịch sử đầy đủ của mỗi dòng mã trước khi thực hiện bất kỳ thay đổi nào, việc có những nhận xét này trong mã sẽ là dư thừa. Nhưng điều này rất phi thực tế cả từ quan điểm quy trình công việc-- hầu hết các nhà phát triển sẽ chỉ thay đổi xác nhận mà không nghiên cứu lịch sử của người đã thêm nó và tại sao - và từ quan điểm công nghệ-- một hệ thống kiểm soát phiên bản sẽ gặp khó khăn khi theo dõi "cùng "Dòng mã nếu nó đã chuyển từ dòng này sang dòng khác hoặc được tái cấu trúc thành một lớp khác. Nhận xét trong mã có nhiều khả năng được nhìn thấy và quan trọng hơn, để nhắc nhở một nhà phát triển tiếp theo lưu ý rằng một thay đổi có vẻ đơn giản có thể không đơn giản như vậy.

Điều đó đang được nói, thay đổi nhận xét nhật ký trong mã nên tương đối hiếm. Tôi không ủng hộ việc thêm bình luận nhật ký thay đổi mỗi khi một chút mã được tái cấu trúc hoặc khi một lỗi thực sự được sửa. Nhưng nếu yêu cầu ban đầu là "Foo là tùy chọn" và ai đó xuất hiện và thay đổi yêu cầu thành "Foo là bắt buộc để hỗ trợ thanh quá trình hạ lưu" thì đó là điều mà tôi rất muốn xem xét khi thêm nhận xét. Bởi vì có khả năng mạnh mẽ là một số người dùng / nhà phân tích trong tương lai sẽ không biết về quy trình Bar hạ lưu và không biết lý do Foo được yêu cầu và sẽ yêu cầu Foo tùy chọn lại và gây đau đầu trong quy trình Bar.

Và điều này là trước khi xem xét rằng các tổ chức có thể quyết định thay đổi hệ thống kiểm soát phiên bản của họ với một số tần suất đặc biệt khi họ phát triển từ các công ty nhỏ với một số ít nhà phát triển sang các công ty lớn hơn nhiều. Những lần di chuyển này thường sẽ dẫn đến việc mất các bình luận nhật ký thay đổi-- chỉ các bình luận trong mã sẽ được giữ nguyên.

Tôi ngạc nhiên khi thấy không ai đề cập đến điều này, nhưng không phải là lý do ban đầu để việc này tuân thủ các yêu cầu cấp phép? Đó là, một số giấy phép nói rằng bất kỳ thay đổi nào bạn thực hiện đối với tệp phải được ghi chú trong chính tệp đó?

Lý do chúng tôi tiếp tục duy trì nhật ký thay đổi trong phần bình luận của chúng tôi là để dễ sử dụng. Thông thường khi gỡ lỗi một vấn đề, việc cuộn lên đầu tệp và đọc nhật ký thay đổi sẽ dễ dàng hơn so với việc mở tệp kiểm soát nguồn, xác định vị trí tệp trong đó và tìm các thay đổi được thực hiện