编写开源Java的最佳实践

Question

在哪里可以找到编写开源Java代码的最佳实践？ 我不是在寻找有关如何正确编写代码的指示，而是寻找分发，打包，文档以及除.java文件之外的所有其他方面的指导。

我的目标是采用我编写的模块并将其作为开源发布。

编辑 - 我仍然缺少有关zip文件应包含的内容的具体说明。是否有这样的惯例，或者我应该选择一些合理的结构？

Answer 1

我不确定是否会就“最佳做法”达成普遍协议，但您提到的项目可能会有简单的答案：

1. 使用java.net或Sourceforge可以轻松分发。您将使用他们的标准发布您的代码，
2. 包装将是ZIP文件。最好创建一个MD5哈希，以使客户能够检查其下载的完整性。
3. 文档 - 是的，请多多。有单独的javadocs和参考指南，展示如何使用你的东西。
4. 拥有一个允许匿名访问的公共SVN，以便人们可以自己获取并构建最新的代码。
5. 有一个错误跟踪器，允许人们报告错误，新功能等。
6. 设置维基以供讨论，反馈等。
7. Maven已经成为一种开源标准。为那些想要签出并构建代码的冒险人士提供一个好的pom.xml。
8. 单元测试和良好的代码覆盖将有助于证明您对质量的承诺。

我会考虑更多。

Answer 2

参见Karl Fogel的书http://producingoss.com/ - 可在线获取的资料。

Answer 3

如果您正在寻找特定的目录结构，为什么不查看现有的开源项目？我从Jakarta Commons开始，这是一个使用频繁的包。

没有任何统计数据支持我，我会说许多项目使用类似于Maven指定的目录结构，即使他们不使用Maven本身（如果你可以通过Maven学习曲线，它有90％的时间都是很好的构建工具。

Answer 4

我没有添加那么多，但我建议如下：

目录结构

• 尝试使javadoc完整，大多数开源模块或库没有很多javadoc注释。生成javadocs文档并将其放在 apidocs 等目录中。如果适用于javadoc，则应指定允许调用类的人员以及应在何种情况下调用类/函数。小代码示例也没有受到伤害，值得添加。
• 添加“examples”目录以提供帮助 开发人员/用户使用/集成 你的模块。
• 在根目录下添加许可证文件 你的目录结构并确保 您的每个文件都有许可证 报头中。
• 在根目录下添加README文件 分发目录 一般信息和/或 细节（链接到软件， 作者，帮助和支持，安装 说明等。）
• 通常源代码进入src目录，文档进入docs文件夹。

<强>包装

• 尝试将软件分发为适当的格式（zip，tar.gz，dmg，exe，jar等）。例如，对于Web应用程序，我会有一个zip，tar.gz，一个战争，也许是一个耳朵。根据您要上传的网站，您可能需要使用zip格式的存档格式。
• 创建安装程序（如果适用或不太繁琐）

<强>出版

• 按照说明（如果适用）上传模块。

• 宣传您的模块（博客，论坛，推特等）

  在打包或上传时始终进行其他测试，可能会发生意外情况（丢失文件，存档损坏等）。

Answer 5

我认为这一切都归结为自动化构建测试包部署周期。理想情况下，您应该只需单击一下（或使用单个提示命令）即可完成此操作。

就个人而言，我使用ant并定义一个部署目标，该目标执行以下操作

1. 构建所有工件
2. 将工件打包成单个可交付物（.zip文件）
3. 将.zip解压缩到本地目录
4. 从该本地目录运行测试套件
5. 将.zip上传到sourceforge

完成后，唯一的手动步骤是通过sourceforge的网站定义新版本。

显然，为了使这个程序有效，你必须被测试感染 - 我为我正在实现的每个新功能编写测试。

Answer 6

如果您的项目名为Foo，那么版本XY应打包在Foo-XYzip中并解压缩到Foo-XY / ....（换句话说，存档中每个文件的路径应以Foo-开头XY /）

将包含基本指令的Foo-X.Y / README.txt作为纯文本文件。它应至少包含有关完整文档的位置的信息（“请参阅docs / index.html for documentation”）以及有关使用的简要说明（“将lib / Foo-XYjar添加到类路径中”）和重建说明（“运行“ant build”以在lib和javadoc中重新生成apidoc /").

中的库

如果您的项目需要额外的库来工作或编译，那么就自动化了。即要么让它成为Maven项目，要么确保它与Ant Ivy一起使用。

我建议在src /下使用源代码，在lib /下构建库，docs /下的文档 - 这是人们所期望的。

Answer 7

使用Apache Maven 2，您将获得所需的所有工件......使用简单的命令“mvn package site”

Answer 8

我建议您为项目托管提供SourceForge（http://sourceforge.net），因为他们有各种各样的工具（博客，维基，源代码控制选项等），而且它们都是免费的。

至于放在zip / jar中的内容......它实际上取决于项目的类型。如果它是一个可重用的库，我建议在存档的根目录中，获得许可证和分发jar。您可以将依赖项放在lib子目录中，将文档放在docs子目录中。

一个例子可能会帮助你更好...下载Jakarta Commons - Lang API（http://commons.apache.org/lang）并查看它们提供的内容。

其他一个答案是使用Maven（http://maven.apache.org）来管理你的项目，我也会推荐这个，不过如果你没有使用它，那么它可以有一点开发人员的学习曲线。 / p>

祝你好运，我希望这会有所帮助。

Answer 9

书：Practical API Design Confessions of a Java Framework Architec t（Jaroslav Tulach，2008，Apress）。

除了书中的提示外，请执行正确的文档（评论，javadocs）并在公共场所（最好是wiki风格）中包含使用示例。使用对于开发人员可能是显而易见的，但对于客户端则不是这样（请参阅JFreeChart作为示例）。