2010-03-24 29 views
9

Tôi tò mò loại nội dung nào nên nằm trong tệp có phiên bản cam kết nhận xét. Nếu nó mô tả chung những gì đã thay đổi (ví dụ: "Màn hình widget đã được thay đổi để chỉ hiển thị widget đang hoạt động") hoặc nên cụ thể hơn (ví dụ: "Điều kiện mới đã được thêm vào mệnh đề where của truy vấn fetchWidget để chỉ truy xuất các tiện ích đang hoạt động theo mặc định ")Thông tin SVN/Versioned cần phải có ý kiến ​​gì?

Cam kết đơn lẻ nên là bao nhiêu? Chỉ cần tệp chứa truy vấn được cập nhật trong một cam kết đơn lẻ (ví dụ: "Cập nhật màn hình tiện ích con để chỉ hiển thị tiện ích đang hoạt động"), hoặc điều đó và một số thay đổi khác + giao diện thay đổi thành màn hình chia sẻ cùng một cam kết với mô tả chung hơn như ("Cập nhật màn hình tiện ích: A) chỉ hiển thị các tiện ích đang hoạt động theo mặc định B) nút được thêm để chuyển đổi các tiện ích không hoạt động")

Tôi thấy subversion cam kết được sử dụng rất khác và đã tự hỏi những gì người khác đã thành công. Một số nhận xét ngắn gọn như "tệp được cập nhật", trong khi một số khác có nhiều đoạn dài và một số khác được định dạng theo cách chúng có thể được truy vấn và liên kết với một số hệ thống bên ngoài như JIRA.

Tôi đã từng mô tả rất rõ lý do thay đổi cũng như các thay đổi kỹ thuật cụ thể. Gần đây tôi đã thu nhỏ lại và chỉ đưa ra một nhận xét chung "Đây là điều tôi đã thay đổi trên trang này".

Trả lời

9

Một số hướng dẫn:

  • không viết những thứ mà hệ thống VC đã theo dõi tự động: các tập tin, bao nhiêu dòng, khi nào, người đã làm thay đổi ...
  • làm viết những gì mục đích của thay đổi là: "thêm hỗ trợ UTF-8 vào thẻ ID3"
  • nếu bạn thấy rằng mục đích không rõ ràng hoặc nhiều, có thể bạn nên thực hiện nhiều cam kết thay thế. Linus Torvalds có thể lấy đi bằng cách viết "các bản sửa lỗi khác nhau trên khắp nơi"; phần còn lại của chúng ta không nên đưa anh ta làm ví dụ.
  • nếu bạn có bất kỳ loại hệ thống theo dõi nào chỉ định số nhận dạng duy nhất cho các vấn đề hoặc yêu cầu tính năng, tất cả có nghĩa là gắn thẻ nhận xét với số nhận dạng đó.
3

Cá nhân, tôi cố gắng tạo một bản tóm tắt ngắn gọn về những gì tôi đã thay đổi và/hoặc được thêm vào. Cái gì đó sẽ nhắc nhở tôi, "Ồ đúng rồi, đây là [có lẽ] nơi tôi đã thêm quy tắc bổ sung đó vào đối tượng kinh doanh." Bởi vì tôi luôn có thể chạy "diff" để xem cụ thể những gì đã thay đổi.

5

cần giải thích ngắn gọn về những gì cam kết chứa. Điều này nên bao gồm số vé để sửa lỗi hoặc tăng cường. Lời khuyên tốt nhất mà tôi từng nghe về việc viết bình luận là "Mã như thể anh chàng tiếp theo duy trì mã của bạn là một kẻ điên cuồng giết người biết bạn sống ở đâu".

1

Một điều giúp tôi khi nghĩ về những gì cần viết/những gì không viết, là cuối cùng có thể biên dịch các ghi chú phát hành kỹ thuật nội bộ từ các nhận xét cam kết.

Tôi cũng nhận thấy nó rất hữu ích để thiết lập thẻ trong cam kết ý kiến, như #doc, #typo, #refactor, ...

tôi sẽ không quá mô tả khi cam kết - những lý do để thực hiện một cái gì đó một cách này hay cách khác nên có trong tài liệu, hoặc trong mã nhận xét IMO.

4

Nhận xét cam kết hữu ích là những nhận xét bổ sung thông tin hữu ích không dễ dàng được trích xuất từ ​​chính các thay đổi.Nhìn vào các khác biệt sẽ hiển thị những gì đã thay đổi, do đó, nhận xét cam kết sẽ tập trung giải thích TẠI SAO những thay đổi được thực hiện:

  • Cố định sự cố do dereference con trỏ NULL (bug ID 234).

  • Đã thêm lệnh để ngắt kết nối khỏi máy chủ (yêu cầu tính năng 22).

  • Làm sạch mã để thay đổi trong tương lai.

Một loại hữu ích của bình luận là một trong đó tóm tắt các mục đích chung của một tập lớn các thay đổi:

  • gia tăng hỗ trợ cho phép người sử dụng để frobulate widget.
3

Nếu bạn sử dụng hệ thống theo dõi lỗi, cách tốt nhất là bao gồm lỗi/nâng cao # bạn đang thực hiện để áp dụng cho thay đổi. Rất nhiều lần bạn sẽ chỉ được viết lại những gì trong mô tả lỗi đó.

2

Cần có một bản tóm tắt nhỏ về các thay đổi (để cho phép lọc trong danh sách thay đổi) và lý do thay đổi được áp dụng.

Tài liệu về mã mới thuộc về chính mã nguồn; không có trong thông điệp tường trình. (Và nhận xét rằng chỉ áp dụng cho mã cũ. Bạn luôn có thể xem các nhận xét cũ đó thông qua lịch sử hệ thống SCC của bạn).

Các vấn đề liên quan