撰写开源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的最佳实践

回答

相关问题