JavaDoc中是否需要作者標記？

無論常見慣例/最佳做法（因爲我知道很多人嘲笑@author是不好的做法），而是依靠官方消息來源，是否需要JavaDoc中的@author標籤？JavaDoc中是否需要作者標記？

調查此問題，我查看了Oracle自己的文檔http://www.oracle.com/technetwork/articles/java/index-137868.html（這也是Google搜索'javadoc標籤'時的第一個結果）。

在一個叫「標籤順序」一節，他們說：

包括以下順序標籤：

@author（類和只，所需的接口）

@version（僅限類和接口，請參見腳註1）

@param（僅限方法和構造函數）

@return（只方法）

@exception（@throws是Javadoc中1.2加入的同義詞）

@see

@since

@serial（或@serialField或@serialData）

@deprecated（見如何以及何時棄用API）

這裏看起來@author被標記爲「必需」，即使@return之類的東西不是。這對我來說似乎很奇怪。事實上，後來就完全一樣的文檔中，我發現了以下聲明：

你可以提供一個@author標籤，多個@author標籤，或沒有@author 標籤。

這在我看來是完全矛盾的。如果您不能提供@author標籤，那肯定不是「必需的」！

我誤解了一些東西，或者這只是寫得不好的文檔嗎？

來源

2016-11-16 Kidburla

「很多人嘲笑爲@author壞習慣......「我從來沒有聽到有人這樣說過。雖然我不認識任何人如果需要考慮'@ author'，那麼我認識的每個人都會對javadoc產生任何價值，似乎很欣賞在對一個類進行基本修改之前能夠諮詢原作者的價值。 – VGR

@VGR例如，在這裏它被描述爲「不需要的噪音」：http://stackoverflow.com/a/17271433/191761 – Kidburla

@Kidburla因此，一個回答就是反對所有關於問責制，審計線索的常識，誰做了什麼什麼時候， ... ？請。 – EJP

我會說寫得不好的文檔。

下段表示：

的@author標籤不是關鍵的，因爲不包括它，當生成API規格，因此它是由那些查看源代碼只看到。（版本歷史記錄，也可用於內部用途確定的貢獻者。）

此外，沒有其中這些技術說明可我看到了一項聲明，要求http://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#javasourcefiles

來源

2016-11-16 23:55:20

你所引用的文件是一個風格指南，而不是javadoc規格：

本文檔介紹了我們在Java軟件，甲骨文寫Java程序的文檔註釋使用的風格指南，標記和圖像約定。

它不是任何東西的「官方來源」，除非您在Oracle工作。

來源

2016-11-16 23:45:33 EJP

JavaDoc中是否需要作者標記？

回答

相關問題