我应该去哪里寻找编写开源Java代码的最佳实践？ 我不是在寻求如何正确编写代码的指导，而是关于分发、打包、文档以及除.java文件之外的所有其他方面的问题。
我的目标是将我编写的一个模块发布为开源。
编辑 - 我仍然缺少有关zip文件应包含什么的直接、具体说明。是否有惯例可循，或者我只需选择一些合理的结构即可？
9个回答
7
我不确定是否会有普遍的“最佳实践”意见，但你提到的几个问题可能有简单的答案：
- 使用java.net或Sourceforge很容易进行分发。您将使用它们的标准发布代码。
- 打包将是ZIP文件。最好创建一个MD5哈希，以便客户端可以检查其下载的完整性。
- 文档 - 是的，请提供大量文档。拥有单独的javadocs和参考指南，显示如何使用您的内容。
- 设置一个公共SVN，允许匿名访问，这样人们就可以自己获取和构建最新的代码。
- 设置一个缺陷跟踪器，允许人们报告缺陷、新功能等。
- 为讨论、反馈等设置一个wiki。
- Maven已成为某种开源标准。对于那些想要查看和构建您的代码的冒险家来说，需要一个良好的pom.xml。
- 单元测试和良好的代码覆盖率将有助于展示您对质量的承诺。
我会继续思考更多的内容。
- duffymo
2
压缩文件中的目录结构是什么？最佳托管位置在哪里？最好包含集成的维基，错误跟踪器，构建系统，并为我节省麻烦... - ripper234
由于这是Java，我假设您将拥有标准的EAR或WAR文件。JAR将成为库或桌面应用程序。当客户下载并解压缩代码时，您决定需要什么就是那种情况下正确的结构。 - duffymo
6
请查看Karl Fogel的书籍http://producingoss.com/ - 源代码在线可用。
- anon
1
这本书看起来不错。谢谢。你也把它发布到免费在线书籍列表中了吗？（另一个问题） - Peter Kofler
4
如果您正在寻找特定的目录结构，为什么不查看现有的开源项目呢？我建议您从Jakarta Commons开始，这是一个广泛使用的包。
没有任何统计数据支持我的说法，但我认为许多项目使用类似于Maven指定的目录结构，即使它们没有使用Maven本身（如果您能够克服Maven的学习曲线，它是一个很好的构建工具90%的时间）。
没有任何统计数据支持我的说法，但我认为许多项目使用类似于Maven指定的目录结构，即使它们没有使用Maven本身（如果您能够克服Maven的学习曲线，它是一个很好的构建工具90%的时间）。
- kdgregory
3
我没有添加太多东西，但我建议以下内容：
目录结构
- 尽量完善javadoc注释，大多数开源模块或库都没有很多javadoc注释。生成javadoc文档，并将其放置在像apidocs这样的目录中。如果适用于javadoc，则应指定谁可以调用类以及在哪些情况下应调用类/函数。小的代码示例也不会有害，值得添加。 - 添加一个“examples”目录，以帮助开发人员/用户使用/集成您的模块。 - 在您的目录结构根目录下添加许可证文件，并确保每个文件都有许可证头文件。 - 在分发的根目录下添加一个README文件，包含一般信息和/或特定信息（链接到软件、作者、帮助和支持、安装说明等）。 - 通常，源代码放在src目录中，文档放在docs文件夹中。
打包
- 尝试将您的软件分发为适当的格式（zip、tar.gz、dmg、exe、jar等）。例如，对于Web应用程序，我会有一个zip、tar.gz、war和可能是ear。根据您要上传的网站，您可能需要使用zip等存档格式。 - 如果适用或不太繁琐，请创建安装程序。
发布
- 如果适用，请按照说明上传您的模块。 - 宣传您的模块（博客、论坛、Twitter等）。 - 打包或上传时始终进行额外的测试，可能会出现意外情况（缺少文件、存档损坏等）。
目录结构
- 尽量完善javadoc注释，大多数开源模块或库都没有很多javadoc注释。生成javadoc文档，并将其放置在像apidocs这样的目录中。如果适用于javadoc，则应指定谁可以调用类以及在哪些情况下应调用类/函数。小的代码示例也不会有害，值得添加。 - 添加一个“examples”目录，以帮助开发人员/用户使用/集成您的模块。 - 在您的目录结构根目录下添加许可证文件，并确保每个文件都有许可证头文件。 - 在分发的根目录下添加一个README文件，包含一般信息和/或特定信息（链接到软件、作者、帮助和支持、安装说明等）。 - 通常，源代码放在src目录中，文档放在docs文件夹中。
打包
- 尝试将您的软件分发为适当的格式（zip、tar.gz、dmg、exe、jar等）。例如，对于Web应用程序，我会有一个zip、tar.gz、war和可能是ear。根据您要上传的网站，您可能需要使用zip等存档格式。 - 如果适用或不太繁琐，请创建安装程序。
发布
- 如果适用，请按照说明上传您的模块。 - 宣传您的模块（博客、论坛、Twitter等）。 - 打包或上传时始终进行额外的测试，可能会出现意外情况（缺少文件、存档损坏等）。
- John Doe
2
我认为这一切都归结于自动化构建-测试-打包-部署的循环。理想情况下，您应该能够通过单击（或单个提示命令）完成此操作。
个人而言，我使用ant并定义了一个部署目标，其中包括以下步骤：
2. 构建所有工件 3. 将工件打包成单个可交付文件（.zip文件） 4. 将.zip解压缩到本地目录中 5. 从该本地目录运行测试套件 6. 将.zip上传到sourceforge 完成上述步骤后，唯一需要手动执行的步骤是通过sourceforge网站定义新版本。
显然，为使此过程有效，您必须进行测试感染 - 我为我正在实施的每个新功能编写测试。
个人而言，我使用ant并定义了一个部署目标，其中包括以下步骤：
2. 构建所有工件 3. 将工件打包成单个可交付文件（.zip文件） 4. 将.zip解压缩到本地目录中 5. 从该本地目录运行测试套件 6. 将.zip上传到sourceforge 完成上述步骤后，唯一需要手动执行的步骤是通过sourceforge网站定义新版本。
显然，为使此过程有效，您必须进行测试感染 - 我为我正在实施的每个新功能编写测试。
- Itay Maman
2
2我想知道为什么这个被投票了 - 我觉得这与我的问题完全无关。是的，自动部署和测试很好 - 但我问的是具体要部署什么，目录结构应该是什么样的，需要提供什么文档等等...而不是如何构建一个部署脚本。 - ripper234
1好的，你提到了分发。这有点离题，但是解决了如何有效地发布的问题。我认为你上面的评论进一步定义了你最初的问题所要求的内容，也许应该进行编辑。 - Brian Agnew
1
如果您的项目名为Foo，则版本X.Y应打包在Foo-X.Y.zip中并解压到Foo-X.Y/...（换句话说，存档中每个文件的路径都应以Foo-X.Y/开头）
有一个Foo-X.Y/README.txt作为纯文本文件包含基本说明。它至少应包含有关完整文档位置的信息（“请参阅docs/index.html获取文档”），以及有关使用说明的简要说明（“将lib/Foo-X.Y.jar添加到类路径中”）和重建说明（“运行“ant build”以在lib中重新生成库和apidoc/中的javadoc”）。
如果您的项目需要其他库才能工作或编译，请自动化处理。即让其成为Maven项目或确保其与Ant Ivy兼容。
我建议将源代码放在src/下，构建的库放在lib/下，文档放在docs/下-这是人们所期望的。
- Thorbjørn Ravn Andersen
0
我建议您使用SourceForge（http://sourceforge.net）作为您的项目托管平台，因为他们拥有各种工具（博客、维基、源代码控制选项等），而且全部都是免费的。
至于要在zip/jar中放什么...这真的取决于项目的类型。如果它是一个可重用的库，我建议在存档的根目录中放置您的许可证和分发jar。您可以将依赖项放在lib子目录中，并将文档放在docs子目录中。
举个例子可能会更好...下载Jakarta Commons - Lang API（http://commons.apache.org/lang）并查看他们提供了什么。
另一个答案是使用Maven（http://maven.apache.org）来管理您的项目，我也推荐这样做，尽管如果您以前没有使用过它，可能需要一些开发人员学习曲线。
祝你好运，希望这能对你有所帮助。
- cjstehno
1
我猜这有点像Thorbjorn的建议，但我会为源代码单独创建一个归档文件（或只是一个源代码控制链接）。正如他所提到的那样，Ant和Ivy也是非常好的工具，尽管它们没有像Maven那样“推送”项目布局......它们更加自由形式。 - cjstehno
0
书籍：Java框架架构师的实用API设计告白（Jaroslav Tulach，2008年，Apress）。
除了书中的提示外，请进行适当的文档编写（注释、javadoc），并在某个公共位置（最好是以wiki风格）包含使用示例。对于开发人员来说，使用可能很明显，但对于客户端来说可能不是这样（例如JFreeChart）。
除了书中的提示外，请进行适当的文档编写（注释、javadoc），并在某个公共位置（最好是以wiki风格）包含使用示例。对于开发人员来说，使用可能很明显，但对于客户端来说可能不是这样（例如JFreeChart）。
- akarnokd
网页内容由stack overflow 提供, 点击上面的可以查看英文原文，
原文链接
原文链接