Thực hành tốt nhất trong viết bình luận và tài liệu

20

Bình luận ngày nay dễ dàng hơn bao giờ hết. Trong Java, có một số kỹ thuật hay để liên kết các bình luận với các lớp và các IDE Java rất tốt trong việc tạo các vỏ nhận xét cho bạn. Các ngôn ngữ như Clojure thậm chí cho phép bạn thêm mô tả về hàm trong chính mã chức năng làm đối số.

Tuy nhiên, chúng ta vẫn sống trong thời đại thường có những bình luận lỗi thời hoặc kém được viết bởi các nhà phát triển giỏi - Tôi quan tâm đến việc cải thiện sự mạnh mẽ và hữu ích của các bình luận của tôi.

Đặc biệt tôi quan tâm đến Java / Clojure / Python ở đây, nhưng câu trả lời không cần phải cụ thể theo ngôn ngữ.

Có bất kỳ kỹ thuật mới nổi nào xác nhận nhận xét và tự động phát hiện các nhận xét "mỏng manh" (ví dụ: nhận xét có số ma thuật, câu không đầy đủ, v.v.) hoặc nhận xét không chính xác (ví dụ: phát hiện các biến sai hoặc tương tự).

Và quan trọng hơn: Có "chính sách bình luận" hay chiến lược nào được chấp nhận không? Có rất nhiều lời khuyên về cách viết mã - nhưng còn "làm thế nào để bình luận?"

— tháng giêng 100
nguồn

40

Tên / tài liệu sẽ cho bạn biết những gì bạn đang làm.
Thực hiện sẽ cho bạn biết làm thế nào bạn đang làm điều đó.
Nhận xét sẽ cho bạn biết lý do tại sao bạn làm theo cách bạn làm.

— quái vật
nguồn

6

các bình luận cũng sẽ cho bạn biết lý do tại sao bạn không làm theo cách khác - tức là các lựa chọn thiết kế quan trọng - bởi vì các nhà bảo trì trong tương lai sẽ không có thông tin này theo cách khác.

2

Tôi tin rằng có nhiều lần một bình luận nên nói NHỮNG GÌ bạn đang làm quá. Ý kiến của tôi về ý kiến "tại sao" là một mô hình chống đối theo ý kiến của tôi. Có một điều hoang đường là bạn có thể viết tất cả mã rõ ràng để bất kỳ lập trình viên nào cũng có thể hiểu được nó trong nháy mắt và kinh nghiệm của tôi là hầu hết các lập trình viên nghĩ rằng họ viết mã sạch. Nó giống như nói, "Tôi không phải đặt tên mô tả cho hàm này bởi vì bất kỳ ai cũng có thể đọc mã trong hàm để xem nó làm gì." - điều đó cũng không có ý nghĩa gì, phải không?

— dallin

2

@dallin nếu mã của bạn không rõ ràng về những gì nó đang làm; xem xét tái cấu trúc nó. mặt khác thêm một nhận xét giải thích lý do tại sao nó được thực hiện như vậy (điều này cũng xảy ra để giải thích cách tốt hơn). So sánh của bạn với tên mô tả là táo / cam, một tên mô tả cho thấy rõ chức năng được sử dụng ở đâu và bạn có thể không có quyền truy cập vào mã nguồn của hàm.

— ratchet freak

@dallin: "Thật hoang đường khi bạn có thể viết tất cả các mã đủ rõ ràng để bất kỳ lập trình viên nào cũng có thể hiểu được nó trong nháy mắt", chú Bob muốn có một lời nói với bạn. - "Tôi không phải đặt tên cho hàm này một cách mô tả bởi vì bất kỳ ai cũng có thể đọc mã trong hàm để xem nó làm gì.", Đặt tên tốt và rõ ràng cho các biến và phương thức chính xác là cách các lập trình viên nên làm rõ mã của họ là gì đang làm

— klaar

14

Điều này có thể gây tranh cãi, nhưng lời khuyên của tôi sẽ là viết bình luận FEW càng tốt. Thay vào đó, sử dụng tên lớp rõ ràng, tên biến và tên phương thức. Viết mã của bạn theo cách rõ ràng nhất mà bạn có thể; và coi đây là thuộc tính quan trọng nhất của mã của bạn (ngoài việc nó đáp ứng các yêu cầu của nó). Chỉ viết nhận xét nếu bạn đã thực hiện một phương pháp rõ ràng nhất có thể và bạn vẫn nghĩ rằng nó cần giải thích thêm.

Và có một thực tiễn tổ chức, rằng bất cứ khi nào bất cứ ai thay đổi một lớp theo bất kỳ cách nào, họ phải đảm bảo các ý kiến vẫn đúng.

— Dawood nói phục hồi Monica
nguồn

1

Đây là một khởi đầu tốt, nhưng tôi nghĩ để thỏa mãn câu hỏi của OP, bạn sẽ cần phải viết một cái gì đó giải quyết mối quan tâm thực sự của anh ấy liên quan đến xác nhận tự động.

— Robert Harvey

2

+1 - Tôi cũng nghĩ rằng các bình luận chỉ nên được sử dụng để giải thích tại sao mã được viết. Tôi biết những gì if (a == b) then c();nó làm, nhưng nếu tôi không biết tại sao nó lại làm điều đó - đó là khi một bình luận nên được sử dụng :)

— Deco

Deco - Tôi hoàn toàn đồng ý. Nhận xét là tốt khi tôi muốn hiểu làm thế nào một phương pháp cụ thể phù hợp với toàn bộ quá trình. Nói cách khác, TẠI SAO bạn gọi phương thức này hoặc TẠI SAO nó làm những gì nó làm.

— Dawood nói phục hồi Monica

Ngoài việc làm cho mã bằng văn bản rõ ràng, chúng ta cũng nên đảm bảo giữ lại các ý tưởng, cấp độ mã, v.v. bằng cách sử dụng các nhận xét TODO. Ví dụ: nếu bạn thấy một chức năng / lớp có thể xử lý đúng kích thước dữ liệu hiện tại, nhưng có khả năng sẽ không xử lý tải sau 2 năm, thì hãy đảm bảo viết quan sát của bạn ở đó bằng cách sử dụng nhận xét TODO. Các nhà phát triển trong tương lai sẽ thực sự đánh giá cao những nỗ lực của bạn. Đừng bao giờ cố gắng lưu ý những điều này trong một tài liệu txt / word riêng biệt, trong khi viết mã, không ai thực sự đề cập đến các tài liệu đó.

— TechCoze

xem thêm: Nhận xét là một mật mã mùi

— gnat

5

Tôi không chắc chắn về các ngôn ngữ khác, nhưng python cho phép bạn viết các tài liệu là một dạng bình luận tự kiểm chứng. Tất nhiên, chúng không nên được sử dụng thay cho thử nghiệm đơn vị thực sự, nhưng là một phương pháp nhanh chóng và dễ dàng để ghi lại các chức năng cụ thể có thể không rõ ràng như chúng cần phải có. Chúng đi kèm với lợi ích bổ sung là có thể thực hiện các bài kiểm tra nhận xét để xác minh rằng các nhận xét vẫn đúng (ít nhất là phần trong số chúng có chứa các bài kiểm tra).

— Josh Smeaton
nguồn

1

Và Sphinx so sánh mã với tài liệu để cung cấp số liệu bảo hiểm.

— S.Lott

3

Một trong những vị trí có thẩm quyền nhất để tìm cách sử dụng nhận xét mã để tạo tài liệu tự động chắc chắn là doxygen . Mặc dù có thể cho tôi nhiều công cụ như vậy.

Điều này xác định tiêu chuẩn viết bình luận cần được tuân theo để tự động tạo tài liệu. Tuy nhiên, điều này mang lại nhiều cấu trúc hơn nhưng không xác nhận về mặt ngữ nghĩa; ví dụ, nó không thể kiểm tra xem bạn đã sử dụng tiếng Anh sai lệch để mô tả mục đích của hàm chưa!

Trong khi, đây là điều tốt nhất khiến các bình luận có cấu trúc, cá nhân tôi cảm thấy có nhiều tài liệu cần thiết để làm cho mã dễ duy trì hơn như vậy. Thỉnh thoảng có một câu hỏi trong P.SE Mã có thể là tài liệu trong các công cụ phát triển nguồn mở không? Nó có thường xuyên không? Tất nhiên, Điều này cũng áp dụng cho các dự án không nguồn mở.

Để làm cho mã dễ bảo trì hơn - thực tế quan trọng hơn là tồn tại một tài liệu bên ngoài giúp tạo cấu trúc về cách xử lý mã, và sau đó các ý kiến bên trong mã phải được hạn chế để xem

Tôi nghĩ, nếu bạn muốn xác định các chính sách cho việc viết bình luận, bạn nên đưa vào như một cách tiếp cận toàn diện có trong tiêu chuẩn mã hóa. Xem điều này: Điều gì có thể là một số cạm bẫy trong việc giới thiệu một hướng dẫn phong cách và phần mềm tạo tài liệu trong một nhóm phát triển?

Thông thường một bình luận cấu thành ít hơn 5% mã. Và trong thực tế trong khi bản thân các bài phê bình mã thu hút ít sự chú ý hơn (so với các khía cạnh khác của sự phát triển) thì thực tế rất khó mà các bình luận cũng được xem xét.

— Mehan
nguồn

1

Tôi không đồng ý với câu cuối cùng ở đây. Tôi vừa hoàn thành một hợp đồng, làm việc dưới một trưởng nhóm, người đã đánh giá rất chi tiết. Các đánh giá của ông luôn bao gồm các ý kiến - cách chúng được diễn đạt, liệu tên biến có chính xác hay không, liệu chúng có chứa tất cả thông tin mà nhà phát triển trong tương lai có thể muốn biết hay không. Không lâu sau, tôi biết những gì anh ấy mong đợi sẽ thấy trong mỗi bình luận, và có thể đưa ra những bình luận theo tiêu chuẩn của anh ấy. Vì vậy, với điều kiện chính sách tổ chức phải có đánh giá mã và bao gồm các nhận xét trong đánh giá mã, thì điều đó sẽ xảy ra.

— Dawood nói phục hồi Monica

Đây thường là loại bình luận duy nhất tôi viết, đặc biệt là các phương pháp để ghi lại những gì đi vào và những gì phát sinh từ nó (tôi làm việc với các ngôn ngữ được gõ lỏng lẻo).

— DanMan

2

Có bất kỳ kỹ thuật mới nổi nào xác nhận nhận xét và tự động phát hiện các nhận xét "mỏng manh" (ví dụ: nhận xét có số ma thuật, câu không đầy đủ, v.v.) hoặc nhận xét không chính xác (ví dụ: phát hiện các biến sai hoặc tương tự).

Có một kỹ thuật được nhiều người biết đến - nó được gọi là "đánh giá mã" và có một người chị tên là "lập trình cặp". Đừng mong đợi bất cứ điều gì "tự động" ở đây.

Và quan trọng hơn: Có "chính sách bình luận" hay chiến lược nào được chấp nhận không? Có rất nhiều lời khuyên về cách viết mã --- nhưng còn "làm thế nào để bình luận?"

"Hoàn thành mã" không chỉ bao gồm tất cả về cách viết mã, mà còn có các chương về "cách nhận xét", đặc biệt là về cách viết mã tự viết tài liệu.

— Bác sĩ Brown
nguồn

+1 cho Mã hoàn thành. Clean Code của Robert Martin cũng có một chương hay về cách viết những lời khen hữu ích. Tôi không chắc chắn về thế giới Java nhưng trong thế giới .NET, chúng tôi có Resharper, có thể 'tự động' xác thực các tham chiếu đến các phần tử mã trong các nhận xét :)

— MattDavey

0

Cụ thể đối với một nguồn Java mà tôi rất thích là Cách viết bình luận tài liệu của Oracle cho Công cụ Javadoc :

Tài liệu này mô tả hướng dẫn về kiểu dáng, thẻ và quy ước hình ảnh mà chúng tôi sử dụng trong các nhận xét tài liệu cho các chương trình Java được viết tại Phần mềm Java, Sun microsystems.

Và Mục 44: Viết nhận xét tài liệu cho tất cả các thành phần API được hiển thị :

Nếu một API có thể sử dụng được, nó phải được ghi lại. Tài liệu API truyền thống được tạo thủ công và giữ cho nó đồng bộ với mã là một việc vặt. Môi trường lập trình Java giúp giảm bớt nhiệm vụ này với tiện ích Javadoc. Javadoc tự động tạo tài liệu API từ mã nguồn với các nhận xét tài liệu được định dạng đặc biệt, thường được gọi là nhận xét tài liệu.

từ phiên bản Java 2 hiệu quả .

— Ái chà
nguồn