Javadoc @author tag thực hành tốt

Question

Tôi đang tự hỏi về các phương pháp hay nhất khi tạo Javadocs. Tôi có một dự án với nhiều tập tin. Mã đã được tạo bởi nhiều nhà phát triển. Mỗi tệp có chú thích @author, vì vậy hiển nhiên ai đã tạo một lớp cụ thể. Tuy nhiên, khi một số nhà phát triển khác thêm mã mới vào một tệp, sửa đổi nó, v.v., làm thế nào anh ta nên thông báo cho các thành viên còn lại của nhóm rằng anh ta đã tạo ra một số chức năng mới hoặc đã sửa đổi mã hiện tại? Nói cách khác, làm thế nào chúng ta nên "giữ cho Javadocs tương thích với thực tế"? ;)

• Thêm tên của mình vào thẻ @author hiện tại? Sau đó, việc xác định ai cần hỏi trong trường hợp có bất kỳ nghi ngờ nào cũng dễ dàng hơn.
• Thêm một thẻ @author vào mỗi phương pháp mới, lớp bên trong, v.v ...?

Tất nhiên, vì chúng tôi sử dụng SVN, thật dễ dàng để điều tra ai đã làm gì, nhưng để giữ mọi thứ rõ ràng, công cụ Javadoc này cũng cần được xem xét.

Cách tốt nhất để sử dụng các thẻ @author này là gì?

Answer 1

Tôi sẽ nói rằng đối với hầu hết các mục đích @author là tiếng ồn không mong muốn. Người dùng API của bạn không nên - và có thể không quan tâm hoặc muốn biết ai đã viết phần nào.

Và, như bạn đã nêu, SVN đã nắm giữ thông tin này một cách có thẩm quyền hơn nhiều so với mã có thể. Vì vậy, nếu tôi là một trong những nhóm, tôi sẽ luôn luôn thích đăng nhập của SVN và bỏ qua các @author. Tôi cá rằng mã sẽ không đồng bộ với thực tế, bất kể chính sách nào bạn đã chấp nhận. Theo nguyên tắc Không lặp lại chính mình, tại sao giữ thông tin này ở hai nơi?

Nếu, tuy nhiên, có một số lý do quan liêu hoặc chính sách mà thông tin này PHẢI được bao gồm trong mã, bạn có cân nhắc tự động cập nhật thẻ @author trong mã khi đăng ký không? Bạn có thể có thể đạt được điều này với móc SVN. Ví dụ, bạn có thể liệt kê tất cả các nhà phát triển đã thay đổi một tệp đã cho theo thứ tự mà họ đã thay đổi nó; hoặc ai thay đổi nó nhiều nhất; hay bất cứ cái gì. Hoặc, nếu @author được bắt buộc trong mã nguồn bạn phát hành ra thế giới bên ngoài, bạn có thể xem xét tự động thêm @author như một phần của bản phát hành (Tôi nghi ngờ bạn có thể lấy thông tin này ra khỏi SVN bằng cách nào đó).

Để thêm nhiều hơn một cấp lớp đơn @author thẻ (hoặc nhận xét khác), tôi muốn nói rằng bạn sẽ tích luỹ được nhiều tiếng ồn vô ích. (Một lần nữa, bạn có SVN.Theo kinh nghiệm của tôi, việc xác định thay đổi lịch sử hữu ích hơn nhiều (nói thay đổi dòng mã hoặc phương pháp), sau đó tìm ra thay đổi nào liên quan đến (và theo dõi vé nào). Sau đó, bạn có ngữ cảnh đầy đủ cho sự thay đổi: bạn có vé, bộ thay đổi, bạn có thể tìm thấy các bộ thay đổi khác trên cùng một vé, hoặc cùng một lúc, bạn có thể tìm thấy vé liên quan và bạn có thể thấy TẤT CẢ những thay đổi hình thành đơn vị công việc đó. Bạn sẽ không bao giờ nhận được điều này từ chú thích hoặc nhận xét trong mã.

Answer 2

Bạn có thể có nhiều hơn một thẻ @author. Trong trường hợp bạn thực hiện một số thay đổi lớn cho một lớp học, chỉ cần thêm một thẻ @author mới với tên của riêng bạn trong đó. Không cần đánh dấu các thay đổi bạn đã thực hiện hoặc đặt tên của bạn xung quanh các thay đổi, vì lịch sử sửa đổi sẽ có thể hiển thị rõ ràng.

Answer 3

Bạn có thể muốn xem xét lý do tại sao bạn muốn thẻ tác giả trong nguồn. Quỹ Apache không và tôi đồng ý.

http://www.theinquirer.net/inquirer/news/1037207/apache-enforces-the-removal-of-author-tags

Để hiểu biết tốt nhất của tôi đây là một hàng hóa sùng bái cách làm việc kể từ khi nguồn được in trên giấy. Với hệ thống kiểm soát phiên bản hiện đại, thông tin này và nhiều thông tin khác có thể được tìm thấy trong lịch sử.

Answer 4

Trong các dự án thực sự lớn và lâu dài với nhiều nhà phát triển, thật hữu ích khi biết ho có trách nhiệm cung cấp mã, người có thể cung cấp cho bạn thông tin bổ sung và như vậy. Trong trường hợp đó, sẽ có ích khi có một thông tin như vậy trong tệp bằng cách sử dụng thẻ @author. Không đánh dấu ai đã tạo tệp hoặc người đã thực hiện một số đóng góp lớn, nhưng ai là người liên hệ cho mã đó. Những người có thể là những người rất khác nhau như tác giả ban đầu có thể đã có trên dự án khác nhau hoặc rời công ty năm trước.

Tôi nghĩ về dự án lớn mà phương pháp tiếp cận có thể hữu ích, tuy nhiên có một báo trước. Việc lưu giữ mọi thông tin tác giả của một tệp đơn là rất khó vì có rất nhiều tệp và sớm hay muộn sẽ không thành công. Ngày càng có nhiều tệp sẽ có thông tin lỗi thời và các nhà phát triển sẽ không còn tin tưởng vào @author như nguồn thông tin này nữa và sẽ bỏ qua nó.

Giải pháp, có thể hoạt động, không được giữ @author trên từng tệp, nhưng chỉ cho mỗi mô-đun (gói cấp cao). Javadoc có một tính năng, nơi bạn có thể ghi tài liệu không chỉ các tập tin mà toàn bộ các gói (See this question for more detail).

Tuy nhiên, đây là trường hợp đặc biệt và miễn là dự án của bạn không lớn hoặc cũ, tôi khuyên bạn nên cập nhật thông tin tác giả.