Q

Bạn có muốn đặt nhận xét về sửa lỗi trong mã nguồn không?

2009-12-09 23 views 9 likes

9

Và nếu có, bạn vẽ đường kẻ ở đâu? Đồng nghiệp của tôi và tôi không đồng ý về chủ đề này. Tôi đã thấy những thứ nhưBạn có muốn đặt nhận xét về sửa lỗi trong mã nguồn không?

// fixes bug # 22

để

// fixed bug: shouldnt be decrementing 
i++;

Is it ok nếu sự thay đổi khá đáng kể, và triệt để thay đổi những gì phương pháp này được viết để làm gì? Hay bạn chỉ đơn giản là thay đổi văn bản tóm tắt của phương pháp để phản ánh những gì nó bây giờ có nghĩa là để làm gì?

Ý kiến của tôi là thông tin này nên được đưa vào kiểm soát nguồn. Một số nhà nước rằng điều này là xấu bởi vì sau đó nó sẽ bị mất bên ngoài bối cảnh kiểm soát nguồn (nói rằng bạn chuyển đổi hệ thống và muốn giữ dữ liệu lịch sử).

2009-12-09 esac

A

Trả lời

32

Nhận xét nên giải thích cách thức các phương thức hoạt động.

Kiểm soát nguồn giải thích lý do tại sao các thay đổi được thực hiện.

2009-12-09 23:02:38

+1

Suy nghĩ của tôi chính xác. –

+1

Không thể đồng ý hơn. – Davie

+0

Những gì được nói ở đây. –

4

Chúng tôi đã có một vài ý kiến như thế này, nhưng sau đó máy chủ Bugzilla của chúng tôi đã chết và chúng tôi khởi động lại ở lỗi # 1 để tất cả chúng đều vô nghĩa. Một lời giải thích ngắn gọn của lỗi là phương pháp ưa thích của tôi bây giờ.

2009-12-09 23:01:45

0

Giả sử nhận xét không thừa (ví dụ: i++; //increment i cổ điển), gần như không bao giờ có lý do để tranh luận chống lại thêm nhận xét, bất kể nhận xét gì. Thông tin hữu ích. Tuy nhiên, tốt nhất là mô tả và súc tích - đừng nói "sửa lỗi #YY", nhưng thay vào đó hãy thêm một cái gì đó như "điều này được sử dụng để thất bại cho x = 0, logic bổ sung ở đây ngăn chặn điều đó". Bằng cách đó, một người xem mã sau có thể hiểu tại sao một phần cụ thể lại quan trọng đối với chức năng thích hợp.

2009-12-09 23:02:48 Amber

+1

... nhưng quá nhiều thông tin được sử dụng * ít * và chỉ thêm tiếng ồn. –

+0

Do đó phần giới thiệu "giả định nhận xét không thừa". Nhận xét vẫn nên có liên quan đến mã, nhưng chỉ vì một lỗi không còn hiện diện không có nghĩa là cảnh báo những người khác mắc lỗi lần nữa không hữu ích. – Amber

+0

Thay vì đề cập đến một lỗi trong quá khứ, nó sẽ không được tốt hơn để nói (ví dụ này), "điều này ngăn chặn một thất bại khi x = 0". –

6

No. Bạn nên giữ thông tin về lỗi và bộ thay đổi sửa lỗi bên ngoài mã nguồn. Bất kỳ ý kiến nào trong chính mã chỉ nên liên quan đến những gì mã đang làm. Bất cứ điều gì khác chỉ là lộn xộn.

2009-12-09 23:03:31 tvanfosson

6

Cá nhân tôi cảm thấy rằng các nhận xét nên nói về chính mã đó chứ không phải về sửa lỗi.

Lý do của tôi cho việc này là bảo trì - 2 (hoặc 10) năm sau, nhận xét này sẽ không còn ý nghĩa nữa. Trong ví dụ của bạn ở trên, tôi muốn một cái gì đó như:

// Increment i to counteract extra decrement 
++i;

Sự khác biệt là nó không gắn với một lỗi, mà là những gì các mã đang làm. Nhận xét phải là nhận xét về mã, chứ không phải thông tin meta, IMO.

ý kiến này là một phần vì tôi duy trì một codebase rất cũ - và chúng tôi có rất nhiều ý kiến mà không liên quan đến sửa lỗi hoặc yêu cầu tăng cường tính năng, vv có ý nghĩa còn ....

2009-12-09 23:03:59

0

Tôi dựa vào FogBugz và nhận xét trong svn. Hoạt động tốt, mặc dù như jeffamaphone cho biết số trường hợp không có nhiều ý nghĩa nếu bạn mất cơ sở dữ liệu lỗi của mình.

Sự cố khi đặt nhận xét trong mã là, theo thời gian, mã của bạn sẽ bị phân tán với các nhận xét về các sự cố chưa tồn tại trong một thời gian. Bằng cách đặt các nhận xét như vậy trong các bình luận đăng ký kiểm soát nguồn, bạn đang gắn kết thông tin hiệu quả về bản sửa lỗi cho phiên bản cụ thể mà nó đã được sửa chữa, điều này có thể hữu ích sau này.

2009-12-09 23:04:02

0

Quan điểm của tôi là nhận xét phải phù hợp với ý định của nhà phát triển hoặc những điểm nổi bật về 'lý do' xung quanh thuật toán/phương pháp.

Nhận xét không được bao quanh bản sửa lỗi đúng thời hạn.

2009-12-09 23:04:13

23

Thêm nhận xét về sửa lỗi là một ý tưởng hay, nếu bạn viết đúng thứ.

Ví dụ,

/* I know this looks wrong, but originally foo was being decremented here, and 
    it caused the baz to sproing. Remember, the logic is negated by blort! */

Stuff như Fixes bug #22là tốt hơn giữ trong kiểm soát nguồn. Nhận xét trong mã của bạn phải là biển chỉ dẫn để giúp những người tham gia tương lai trên đường đi của họ, không đáp ứng quy trình và theo dõi.

2009-12-09 23:04:41 erickson

+9

+1. Một nhà lý tưởng sẽ nói điều gì đó như "Bình luận nên giải thích cách thức các phương thức hoạt động. Kiểm soát nguồn giải thích tại sao những thay đổi được thực hiện". Điều này bỏ qua thực tế là khi bạn đọc mã phức tạp, nó giúp biết tại sao nó làm điều gì đó không rõ ràng, và đề cập đến trường hợp ảnh hưởng đến cách nó được viết là cách tốt nhất để giải thích điều này. – Edmund

+1

Vâng, ví dụ bình luận giải thích cách thức hoạt động của phương thức. với một chút bối cảnh lịch sử ném vào. – Martin

+0

Đồng ý, một lần trong một thời gian bạn phải đặt một cái gì đó trong đó giải thích lý do tại sao bạn đang làm một cái gì đó mà sẽ trông ngu ngốc hầu hết thời gian. – jcollum

0

Tôi đồng ý rằng dữ liệu đó nên được đặt trong điều khiển nguồn hoặc một phần Quản lý cấu hình khác. Đã từng làm việc trong các codebases đặt thông tin về các bản sửa lỗi trong các bình luận, tôi có thể nói nó dẫn đến các nhận xét và đoạn mã lộn xộn sau này. Sáu tháng sau khi sửa chữa được đặt ra, bạn có thực sự muốn biết rằng về một dòng sửa chữa một số lỗi trong quá khứ? Bạn làm gì với nhận xét khi bạn cần cấu trúc lại mã?

2009-12-09 23:05:31 Andrew

2

Giống như // fixes bug # 22 hoàn toàn vô nghĩa, và yêu cầu các bước bổ sung để có ý tưởng về ý nghĩa của nó và vai trò của nó. Mô tả ngắn gọn theo ý kiến của tôi thích hợp hơn, bất kể phần mềm theo dõi lỗi hoặc phần mềm kiểm soát nguồn bạn có thể đang sử dụng.

2009-12-09 23:05:50 luvieere

1

Nếu thuật toán cần được mã hóa theo một cách nhất định - để giải quyết lỗi trong API của bên thứ 3 chẳng hạn, thì phải được nhận xét trong mã để người tiếp theo đến cùng không cố gắng " tối ưu hóa "mã (hoặc bất kỳ điều gì) và giới thiệu lại một vấn đề.

Nếu điều này liên quan đến việc thêm nhận xét khi bạn sửa lỗi gốc thì hãy thực hiện.

Nó cũng sẽ đóng vai trò như một điểm đánh dấu để bạn có thể tìm mã bạn cần kiểm tra xem bạn có bao giờ nâng cấp lên phiên bản tiếp theo của API hay không.

2009-12-09 23:07:48 ChrisF

0

Chúng tôi sử dụng Team Foundation Server để kiểm soát nguồn tại công ty của tôi và nó cho phép bạn kiểm tra một báo cáo lỗi, vì vậy tôi sẽ không đưa bình luận trực tiếp vào mã vào máy chủ cùng mục đích.

Tuy nhiên, trong trường hợp tôi triển khai mã như giải pháp cho lỗi trong khuôn khổ .NET hoặc thư viện của bên thứ ba, tôi muốn đặt URL vào nhật ký hoặc trang web Microsoft TechNet mô tả lỗi và trạng thái của nó.

2009-12-09 23:10:07

+0

Right - một liên kết đến một lỗi * mở * là một cái gì đó khác nhau. –

0

Vì vậy, rõ ràng là

// fix bug #22 
    i++;

không phải là giao tiếp hiệu quả.

Giao tiếp tốt chủ yếu là thông thường. Nói những gì bạn có nghĩa là.

// Compensate for removeFrob() decrementing i. 
    i++;

Bao gồm số lỗi nếu có vẻ như có khả năng giúp người đọc trong tương lai.

// Skipping the next flange is necessary to maintain the loop 
    // invariant if the lookup fails (bug #22). 
    i++;

Đôi khi các cuộc trò chuyện quan trọng được ghi lại trong hệ thống theo dõi lỗi của bạn. Đôi khi một lỗi dẫn đến một cái nhìn sâu sắc quan trọng thay đổi hình dạng của mã.

// Treat this as a bleet. Misnomed grotzjammers and particle 
    // bleets are actually both special cases of the same 
    // situation; see Anna's analysis in bug #22. 
    i++;

2009-12-10 19:47:38

+0

Một số khác: số lỗi là siêu liên kết. Mã hiện tại và các lỗi cũ thường không liên quan, nhưng đôi khi chúng là và một liên kết là thích hợp. –

0

Trong kho lưu trữ nguồn Perl5, nó thường được gọi là lỗi, với số Trac được liên kết trong tệp Kiểm tra.

Điều này có ý nghĩa hơn đối với tôi, bởi vì việc thêm một thử nghiệm cho một lỗi sẽ ngăn chặn lỗi đó không bao giờ bị phát hiện một lần nữa.

2009-12-11 00:17:13

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