撰寫開源Java的最佳實踐

我在哪裏可以找到一些編寫開源Java代碼的最佳實踐？我不是在尋找關於如何編寫代碼的指導，而是在分發，打包，文檔以及除.java文件之外的所有其他方面。撰寫開源Java的最佳實踐

我的目標是將我編寫的模塊作爲開源代碼發佈。

編輯 - 我仍然缺少關於什麼zip文件應該包含直接，具體的指示。有沒有公約，或者我應該選擇一些合理的結構？

來源

2009-07-04 ripper234

查看Karl Fogel的書http://producingoss.com/ - 可在線獲得資源。

來源

2009-07-04 10:41:39

這本書看起來不錯。謝謝。你是否也將其發佈在免費在線書籍的列表中（另一個問題） – 2010-07-09 21:44:24

我不知道是否會有關於「最佳做法」普遍同意，但你提到的項目可能有簡單的答案：

分佈很容易與java.net或Sourceforge上。您將使用他們的標準發佈您的代碼，
打包將是ZIP文件。創建一個MD5哈希值以使客戶端可以檢查其下載的完整性是一個不錯的主意。
文檔 - 是的，很多請。有單獨的javadoc和一個參考指南，顯示如何使用你的東西。
有一個公開的SVN允許匿名訪問，所以人們可以自己獲取並構建最新的代碼。
有一個bug跟蹤系統，使人們對錯誤，新功能報告等
設立討論，反饋的維基等
的Maven已經成爲一個開源標準的東西。爲想要簽出並構建代碼的冒險傢伙準備好一個良好的pom.xml。
單元測試和良好的代碼覆蓋率將有助於展示您對質量的承諾。

我會試着想更多。

來源

2009-07-04 10:43:54 duffymo

zip文件中的目錄結構？舉辦此活動的最佳場所是什麼？首先，它將包含集成的wiki，bugtracker，構建系統併爲我節省麻煩...... – ripper234 2009-07-04 11:13:02

既然是Java，我假設你會有一個標準的EAR或WAR。 JAR將成爲圖書館或桌面應用程序。當客戶下載並解壓縮你的代碼時，無論你決定什麼，都是正確的結構。 – duffymo 2009-07-04 11:35:54

我認爲這都歸結爲自動化構建測試包部署週期。理想情況下，您應該可以通過單擊（或使用單個提示命令）來完成此操作。

就個人而言，我使用螞蟻和限定deploy目標，其執行以下操作

構建所有工件

軟件包的工件到一個單一的交付（.zip文件）

解壓的.zip到本地目錄

奔流從本地目錄

上傳測試套件的.zip到sourceforge的

完成這一步之後，唯一的手動步驟是通過sourceforge的網站定義一個新版本。

顯然，爲了使這個過程有效，你必須被測試感染 - 我爲我正在實現的每個新功能編寫測試。

來源

2009-07-04 10:44:32

我不知道爲什麼這會得到一票 - 我覺得這與我的問題完全無關。是的，自動部署和測試是很好的 - 但我在問什麼要部署的細節，目錄結構應該是什麼，提供什麼文檔等等。而不是如何構建部署腳本。 – ripper234 2009-07-04 11:22:25

如果您正在尋找特定的目錄結構，爲什麼不看現有的開源項目？我會從Jakarta Commons開始，這是一個使用頻繁的軟件包。

沒有任何統計數據支持我，我想說許多項目使用類似於Maven指定的目錄結構，即使它們本身不使用Maven（並且如果您可以通過Maven學習曲線，90％的時間它是一個很好的構建工具）。

來源

2009-07-04 12:19:13 kdgregory

我不加那麼多，但我會建議如下：

目錄結構

儘量使的javadoc完整，最開放源碼的模塊或庫沒有太多javadoc評論。生成javadocs文檔，並將它放在一個目錄中，如apidocs。如果適用於javadocs，則應指定允許誰調用某個類，以及在哪些情況下應該調用該類/函數。小的代碼示例也不會受到傷害，值得添加。
添加「examples」目錄以幫助開發人員/用戶使用/集成您的模塊。
在您的目錄結構的根目錄處添加一個許可證文件，並確保您的每個文件都有一個許可證標頭。
在分佈的根目錄添加一個README文件一般信息和/或細節（鏈接到軟件，作者，幫助和支持，安裝指令等）
通常源代碼進入src目錄，文檔進入docs文件夾。

包裝

試試你的軟件分配到合適的格式（拉鍊，tar.gz的，傷害，EXE，罐子等）。例如，對於一個Web應用程序，我會有一個zip，tar.gz，一場戰爭，也許還有一個耳朵。根據您要上傳到的網站，您可能需要使用zip等歸檔格式。
創建一個安裝（如果適用）或不是太繁瑣

出版

按照說明如果適用於上傳您的模塊。
宣傳您的模塊（博客，論壇，微博等）

始終進行其他測試時包裝或上載，意想不到的事情可能發生（丟失的文件，檔案損壞等）。

來源

2009-07-04 13:09:06

如果您的項目被命名爲富，那麼版本XY應包裝在富-XYzip並解壓到foo-XY/....（換句話說，每個文件的存檔中的路徑應從Foo-X開始。Y /）

將Foo-X.Y/README.txt包含爲基本指令作爲純文本文件。它至少應包含關於完整文檔位置的信息（「請參閱文檔docs/index.html」）以及關於使用的簡要說明（「將lib/Foo-XYjar添加到您的類路徑中」）以及重建指令（「運行「ant build」來重新生成lib和javadoc中的庫文件「apidoc /」）。

如果您的項目需要額外的庫來工作或編譯，然後自動化。即或者讓它成爲一個Maven項目或者確保它與Ant Ivy一起工作。

我建議讓src /下的源代碼，lib /下的內置庫，docs下的文檔/ - 這是人們所期望的。

來源

2009-07-04 14:41:49

使用Apache Maven 2，你會得到你所需要的所有工件......一個簡單的命令「MVN包網站」

來源

2009-07-05 23:32:17

我建議SourceForge上（http://sourceforge.net）爲您的項目託管，因爲他們有各種各樣的工具（博客，wiki，源代碼控制選項等），它都是免費的。

至於在zip/jar中放置什麼......它取決於項目的類型。如果它是一個可重用的庫，我會建議在檔案的根目錄下，有你的許可證和你的發行版。您可以將依賴關係放在lib子目錄中，將文檔放在docs子目錄中。

一個例子可能會幫助你更好地...下載Jakarta Commons - Lang API（http://commons.apache.org/lang）並查看它們提供的內容。

其中一個答案是使用Maven（http://maven.apache.org）來管理你的項目，我也會推薦這個，不過如果你之前沒有用過它，可能會有一點開發人員的學習曲線。

祝你好運，我希望這會有所幫助。

來源

2009-07-14 21:06:25 cjstehno

Book：Practical API Design Confessions of a Java Framework Architect（Jaroslav Tulach，2008，Apress）。

除了本書中的提示之外，請做一個正確的文檔（評論，javadocs），並在某處公開使用樣本（最好以wiki風格）。對於開發者來說，使用可能是顯而易見的，但對客戶端來說則不是這樣（請參閱JFreeChart作爲示例）。

來源

2009-07-14 21:27:31 akarnokd

撰寫開源Java的最佳實踐

回答

相關問題