Nói chung có hữu ích khi đưa các vấn đề của JIRA vào bình luận mã không?

Thỉnh thoảng, tôi để lại bình luận như

# We only need to use the following for V4 of the computation.
# See APIPROJ-14 for details.

hoặc là

# We only need to use the following for V4 of the computation.
# See https://theboringcompany.atlassian.net/browse/DIGIT-827 for details.

Mối quan tâm chính của tôi khi làm như vậy là nó làm tăng sự phụ thuộc của chúng tôi vào JIRA, vì vậy những nhận xét đó sẽ hoàn toàn không có ý nghĩa nếu chúng tôi chuyển sang hệ thống quản lý dự án khác. Mặc dù tôi không thấy trước điều đó xảy ra trong tương lai gần, tôi vẫn cảnh giác với sự kết hợp ngày càng tăng của các thành phần tổ chức (trong trường hợp này: mã, kho lưu trữ mã và hệ thống quản lý dự án).

Tuy nhiên , tôi thấy lợi ích của việc có các tham chiếu đến các quyết định thiết kế được ghi lại và cảm hứng tính năng trong toàn bộ cơ sở mã. Theo như tôi có thể nói, lợi ích là

1. một đường dẫn rõ ràng để quyết định thiết kế, giúp gỡ lỗi và tăng cường các phân đoạn cụ thể của mã lạ,
2. Nhận xét nhiều dòng ít hơn, làm cho mã có vẻ sạch hơn / ít đáng sợ hơn với những người đóng góp mới,
3. một con đường rõ ràng đến (có khả năng) các bên liên quan kỹ thuật và phi kỹ thuật hiện tại, và
4. giảm số lượng câu hỏi "tại sao lại ở đây" vì những điều đã nói ở trên.

Tôi sẽ cố gắng tránh những bình luận như vậy. Mặc dù tôi nghĩ rằng có một nơi dành cho họ, nơi bạn có một yêu cầu đặc biệt khó chịu. Mà không có, bất cứ ai cũng có thể muốn cấu trúc lại mã. ví dụ.

//must log to the database instead of standard logging, 
//stupid requirement from those crazy DBAs!! see TKCT-1234

hoặc tương tự bạn có thể đặt trong một liên kết

//work around stolen from this stackoverflow answer http://stackoverflow....

Nhưng không phải vì lý do bạn tăng trạng thái khớp nối. Trong thực tế, tôi đặt tên cho tất cả các chi nhánh tính năng của mình sau vé họ dành cho. Vì vậy, có thể theo dõi tất cả các công việc trở lại một vé nếu được yêu cầu, mặc dù lịch sử cam kết. (bạn cũng có thể thực hiện một số công cụ tự động đóng thông minh nếu bạn cảm thấy thông minh)

Không, tôi không lo lắng về việc thay đổi hệ thống bán vé. Nhưng những gì tôi đã nhận ra là rất hiếm khi ai đó nhìn lại vé một khi chúng được thực hiện.

Vì vậy, nhận xét là hữu ích vì nó nói với sự thay thế trong tương lai của bạn:

"Không, tôi đã không phạm sai lầm, ai đó nói với tôi rằng nó phải theo cách này. Hãy nhìn xem! Đây là số vé để chứng minh điều đó!"

Nhưng họ sẽ không đi và kiểm tra vé đó. Cuộc sống quá ngắn ngủi.

Nếu bạn có thói quen đặt bình luận tham khảo vé ở mọi nơi, thì họ sẽ mất tác động. Thay vì là một lá cờ "đọc cái này thì nó cực kỳ quan trọng!" họ chỉ trở nên lộn xộn.

Nói chung các yêu cầu phải được ghi lại thông qua các phương tiện thử nghiệm. Nếu các bài kiểm tra được thông qua, thì các yêu cầu phải được đáp ứng, chúng tôi không phải lo lắng về cách chúng được nêu ban đầu.

Đối với bình luận mã, có rất ít hữu ích. Đối với các bình luận kiểm soát phiên bản, chúng rất hữu ích cho các lý do được nêu dưới đây.

Nhận xét mã thực sự nên được sử dụng để giúp hiểu ý định của những điều phức tạp.

Các loại bình luận mã xấu:

• Updated EHS 10/24/2015 - nếu tôi muốn biết điều đó, tôi sẽ sử dụng kiểm soát phiên bản để tìm ai đã viết những dòng nào.
• For spec 0.4 - đó có thể là một phần của các nhận xét cam kết, nhưng nó không giúp tôi hiểu mã hơn
• Các biến thể khác của cùng một loại điều.

Nếu bình luận mã tồn tại, họ sẽ giúp hiểu cách khối mã liên quan đến miền doanh nghiệp.

Nếu JIRA và kiểm soát phiên bản của bạn được liên kết thì có, chúng có ý nghĩa đối với các thông báo Cam kết .

• Tham khảo vé cung cấp truy xuất nguồn gốc cho những thay đổi cần thiết cho công việc được yêu cầu
• JIRA không phải là công cụ theo dõi vé duy nhất có khả năng đồng bộ hóa này.

Tôi thực sự khuyên bạn nên một định dạng bình luận như sau:

 DIGIT-827: We only need to use the following for V4 of the computation.

JIRA và bất kỳ công cụ nào có tích hợp này đều đủ thông minh để nhận ra số vé và liên kết nó với vé được giải quyết. Điều đó có nghĩa là một URL đầy đủ là không cần thiết . Điều đó cũng có nghĩa là bạn có thể nhận được những lợi ích và cung cấp những nhận xét có ý nghĩa cho tất cả các cam kết cụ thể trong một dòng.

Khi xem vé trong JIRA, bạn sẽ thấy danh sách các thay đổi với tất cả các nhận xét trong ngữ cảnh với mô tả, v.v.

Có, nhưng chỉ trong những trường hợp hiếm hoi.

Nói chung, tôi tưởng tượng hầu hết các mã sẽ được viết liên quan đến vé JIRA, vì vậy tôi sẽ không thường xuyên nhận xét nó với id vé - đó là điều mà git đổ lỗi cho. Nhưng trong một số trường hợp, mã có thể phản tác dụng - có lẽ cách rõ ràng nhất để viết mã không hoạt động và đã có một số cuộc thảo luận về lý do tại sao không có trên vé. Trong trường hợp đó tôi sẽ xem xét thêm một bình luận với tham chiếu vé.

Nếu một phần của mã cần khắc phục một lỗi đã biết ở phần khác thì tôi cũng sẽ xem xét thêm một tham chiếu vé.

Tôi không nghĩ rằng điều này ràng buộc bạn quá chặt chẽ với JIRA, vì nếu bạn muốn di chuyển từ JIRA sang một hệ thống khác, bạn có thể xuất các vấn đề JIRA của mình dưới dạng CSV và nhập chúng vào hệ thống khác. ID vấn đề có thể thay đổi trong quá trình đó, nhưng bạn sẽ có thể giữ ID vé JIRA ở đâu đó trên vé đã nhập.

Đặt các vấn đề của Jira trong các bình luận cam kết, sau đó sử dụng một plugin để liên kết các cam kết với Jira thực tế.
Thông điệp cam kết của chúng tôi bắt đầu bằng:

JIRA: XBVS-1222 Fixes bugs...

Ví dụ, sau đó móc nối giữa bitbucket và jira liên kết các cam kết với jira. Sau đó, thật dễ dàng để xem Jira mà nó liên quan đến nhật thực chẳng hạn, bằng cách nhấp chuột phải vào số hàng và chọn "Hiển thị lịch sử sửa đổi" Tôi nghĩ dù sao nó cũng được gọi là như vậy. Số vấn đề và nhận xét Jira của bạn sẽ được tô sáng trên cột số hàng và di chuột bằng chuột sẽ cung cấp cho bạn thông tin chi tiết.

Đây chắc chắn không phải là một thực tiễn khủng khiếp khi bao gồm các vấn đề của JIRA trong các nhận xét về mã, nhưng kỹ thuật này kết hợp chặt chẽ / thủ công hai mối quan tâm khác nhau (vấn đề và mã) và có thể yêu cầu cập nhật cho nhiều hệ thống / địa điểm (JIRA, bất cứ nơi nào trong nguồn có vấn đề được đề cập, lịch sử kiểm soát phiên bản).

Nhận xét mã nói chung là có vấn đề vì chúng thường không được cập nhật.

Một cách tiếp cận tốt hơn sẽ là tìm cách tích hợp hệ thống theo dõi vấn đề của bạn với hệ thống kiểm soát phiên bản của bạn, để hai mối quan tâm có thể được duy trì một cách riêng biệt, theo cách tự động.