Mã tự viết tài liệu vs Javadocs?

Gần đây tôi đã làm việc để tái cấu trúc các phần của cơ sở mã mà tôi hiện đang xử lý - không chỉ để hiểu rõ hơn về bản thân mà còn giúp những người khác đang làm việc với mã dễ dàng hơn.

Tôi có xu hướng nghiêng về phía suy nghĩ rằng mã tự viết là tốt . Tôi chỉ nghĩ rằng nó sạch hơn và nếu mã nói cho chính nó, thì ... Thật tuyệt .

Mặt khác, chúng tôi có tài liệu như javadocs. Tôi cũng thích điều này, nhưng có một rủi ro nhất định rằng các bình luận ở đây đã lỗi thời (tất nhiên cũng như các bình luận nói chung). Tuy nhiên, nếu chúng được cập nhật, chúng có thể cực kỳ hữu ích để nói, hiểu một thuật toán phức tạp.

Các thực hành tốt nhất cho việc này là gì? Nơi nào bạn vẽ ranh giới giữa mã tự viết tài liệu và javadocs?

Mã tự viết tài liệu (và nhận xét trong mã) và nhận xét Javadoc có hai đối tượng mục tiêu rất khác nhau.

Mã và ý kiến ​​còn lại trong tệp mã dành cho nhà phát triển. Bạn muốn giải quyết mối quan tâm của họ ở đây - làm cho nó dễ hiểu mã làm gì và tại sao mã lại như vậy. Việc sử dụng tên biến, phương thức, lớp thích hợp, v.v (mã tự ghi) cùng với các bình luận đạt được điều này.

Các bình luận Javadoc thường dành cho người dùng API. Đây cũng là những nhà phát triển, nhưng họ không quan tâm đến cấu trúc bên trong của hệ thống, chỉ các lớp, phương thức, đầu vào và đầu ra của hệ thống. Mã được chứa trong một hộp đen. Những nhận xét này nên được sử dụng để giải thích cách thực hiện một số tác vụ nhất định, kết quả hoạt động dự kiến ​​là gì, khi ngoại lệ được ném và giá trị đầu vào có ý nghĩa gì. Đưa ra một bộ tài liệu do Javadoc tạo, tôi sẽ có thể hiểu đầy đủ cách sử dụng các giao diện của bạn mà không cần nhìn vào một dòng mã của bạn.

Mã nói thế nào . Bình luận nói tại sao , và có lẽ tại sao không .

Công việc của bạn là cung cấp cả cho người đọc và người duy trì mã trong tương lai. Đặt tất cả những gì bạn có thể vào mã, và phần còn lại trong các bình luận.

Lưu ý rằng những điều khó nắm bắt nhất là các quyết định thiết kế - hãy nhớ những điều đó.

Việc sử dụng Javadocs không tạo ra sự khác biệt thực sự - vì các tài liệu được tạo có chứa tên hàm của bạn cùng với văn bản từ các bình luận, hoàn toàn không có lý do nào khiến bạn phải lặp lại bất cứ điều gì trong các bình luận rõ ràng từ chính tên hàm.

Mặt khác, nếu bạn có một chức năng mà người ta phải xem xét việc triển khai trước để hiểu nó tốt cho cái gì (do đó không cung cấp thông tin này cho Javadocs), thì mã đó là IMHO không tự ghi lại, bất kể Làm thế nào rõ ràng việc thực hiện là.

Tôi nghĩ rằng với javadocs, mọi thứ đều giống như với bất kỳ tài liệu nào cả - quy tắc chính là:

theo dõi khán giả

Có nhiều người đọc javadocs của bạn? Nếu có, nó có ý nghĩa tốt để đầu tư nỗ lực để làm cho nó đúng.

Độc giả của bạn có xu hướng bỏ qua việc đọc mã có lợi cho việc nghiên cứu javadocs? Nếu có, nó có ý nghĩa gấp đôi khi dành những nỗ lực để viết nó tốt.

• Đây chính xác là trường hợp với tài liệu JDK . Guess Sun / Oracle đã dành rất nhiều nỗ lực cho những điều này và họ dường như có một sự hoàn vốn tốt đẹp trong các tài liệu API đang được cộng đồng sử dụng rất nhiều.

Bây giờ, đó là trường hợp của bạn? Nếu không, hãy suy nghĩ kỹ xem những nỗ lực đầu tư vào javadocs có hợp lý hay không.

Như đã chỉ ra ở trên, lắng nghe khán giả để tìm ra cách.

• Nếu bạn nghe thấy những khiếu nại tích cực về tài liệu không đầy đủ, hãy xem xét đầu tư vào việc cải thiện nó.
   
  Mặt khác, nếu tất cả những gì bạn nghe được là các nhà phát triển than vãn về các quy tắc bản lĩnh buộc họ phải lãng phí thời gian cho việc đánh máy vô dụng, thì có khả năng cao là những nỗ lực javadocs của bạn giống như đầu tư vào các khoản thế chấp dưới chuẩn . Thay vào đó hãy nghĩ đến những khoản đầu tư tốt hơn.

Tôi chỉ muốn bình luận về mối quan tâm rằng các bình luận Javadoc có thể bị lỗi thời. Mặc dù @JonathanMerlet đã đúng khi nói rằng Javadoc phải ổn định, bạn cũng có thể giúp đỡ bằng cách xem lại Javadoc và các nhận xét cũng như mã trong quá trình đánh giá ngang hàng. Các ý kiến ​​có khớp với những gì mã đang làm không? Nếu không, đó là không chính xác, và yêu cầu nhà phát triển sửa nó. Cố gắng khuyến khích các nhà phát triển khác làm điều tương tự. Điều này giúp không chỉ cập nhật tài liệu bên ngoài (bình luận Javadoc) mà còn bất kỳ bình luận mã thông thường nào. Điều này giúp các nhà phát triển đi cùng sau khi tái cấu trúc của bạn hiểu mã nhanh hơn và dễ dàng hơn và giúp việc duy trì mã đơn giản hơn nhiều trong tương lai.

Tôi nghĩ rằng javadocs phù hợp với các phần nên ổn định (API) để giảm thiểu rủi ro cho các bình luận lỗi thời, trong khi mã tự ghi lại là tuyệt vời cho những gì có thể thay đổi thường xuyên (triển khai). Tất nhiên, các API có thể thay đổi trong quá trình thực hiện dự án, nhưng có tiêu đề ngay trước khi khai báo, giữ cả hai đồng bộ hóa không khó lắm (so với nhận xét về nhiều dòng giải thích một số dòng mã)