有沒有爲javafx應用程序編寫javadocs的任何一點？

簡單的問題在這裏。是否有必要將javadoc應用於javafx應用程序中的方法。有沒有爲javafx應用程序編寫javadocs的任何一點？

對於初學者 - 我的方法標題的大部分格式爲private（與@FXML註釋）。我正在使用一些public方法 - 但如果最終用戶使用GUI與應用程序進行交互並且我的應用程序不是API，那麼javadocs中的要點是什麼？顯然，我所有的方法都是簡明扼要的評論 - 但我不認爲javadocs對用戶或代碼的未來開發人員有什麼好處。

我錯了嗎？如果是這樣，我會非常感謝你對此的看法。非常感謝。

來源

2015-11-03 Dylan White

如果您的項目是由*團隊*而非僅僅由您開發的，那麼您就需要這些文檔。 =）---主要/當前開發者很少存在文檔（javadocs或不）;有人在項目中積極工作，往往會有自己的內部映射關於每個東西在哪裏以及每個東西的作用......並且大多數人只會因相當大的項目而失敗。 ---你爲現在正在進行項目工作的人做文件;即使您不希望除您或您當前的團隊以外的任何人蔘與其中，只是因爲這可能會改變。 – XenoRo

好的，謝謝@TheLima。即使重新。 '私人'@ FXML'方法？ –

是......理論上講，你可以完全記錄的每種方法都應該記錄下來。但是，實際上，您可能會將文檔與方法的重要性和/或直觀性進行權衡;儘管在討論Javadocs和類似的問題時，我仍然建議您至少指定所需的參數和輸出，即使對於那些IDEs也支持它們，並且從JavaDoc工具提示窗口（如NetBean's）中查看它們的內容更容易，必須打開類/方法源代碼才能查看內聯註釋。 – XenoRo

請看看https://softwareengineering.stackexchange.com/questions/85910/is-it-wrong-not-to-create-javadoc-for-my-code

從理論上來說，有意義的文件從來都不是壞的，因此每次可以以有意義的方式記錄方法應記錄在案。

實際上，歸結爲文檔的「受衆」是誰，團隊協議以及個人選擇。

需要考慮的因素有：

觀衆能是維護開發商，其中，請不要介意其他人，可能是自己，3年後沒有工作或遊覽項目，以後你已經忘記了它是如何工作的細節。
對於Javadoc和類似的文檔工具和標準，即使對於私有方法（通常不會默認輸出到外部doc文件），許多IDE支持Javadoc（或類似）並基於它們實現額外功能。例如，NetBeans可以顯示包含類型，名稱的工具提示，並且如果記錄了它們，則可以顯示類，方法以及輸入和輸出參數和變量的用途。 消除了打開文件和/或查看源代碼行內註釋當您忘記了某些內容的需要。

來源

2015-11-03 13:41:38 XenoRo

對於框架代碼，我總是Javadoc所有公共和受保護的成員。對於應用程序代碼，我通常不打擾Javadoc的評論，但是我使用內聯評論來解釋一種方法在做什麼。

對於私有方法（無論是框架還是應用代碼），我根本不使用Javadoc，因爲它們默認不包含在Javadoc輸出中。儘管如此，我仍然使用私人成員的內嵌評論。

來源

2015-11-03 13:46:39

正如我在OP的評論中所解釋的那樣，即使對於私有方法，JavaDocs仍然很有用，因爲許多IDE都支持它們，並且可以基於它們向您顯示工具提示，從而消除了打開文件和/或查看內聯註釋的源代碼。 ---在這種情況下，總是建議使用文檔，但是與編程中的任何東西一樣，它都取決於個人的選擇和/或經驗。 – XenoRo

@TheLima如果您還沒有打開源代碼，您將如何使用（在任何意義上）私有方法？ –

例如，如果你有一個大文件，私人類或方法，工具提示可以讓你訪問同一文件中的其他類或方法，甚至是變量的javadoc解釋，而不必滾動文件來檢查內聯評論。 – XenoRo

有沒有爲javafx應用程序編寫javadocs的任何一點？

回答

相關問題