Java项目文档

Question

5

我需要记录一个Java项目。我是一名C#程序员和系统分析师，但我对Java还很陌生。

我已经从SVN检出了目录。

这些目录包括源目录、WEB-INF以及其他用于定义项目、classpath等的文件。

我知道这些文件基本上属于以下三类之一：

1. 基于包结构的源代码文件/目录(.Java) 2. 用于项目定义、编译器设置等的目录/文件 3. 部署所需的文件。

该项目（像大多数Java项目一样）是一个基于Eclipse的项目，旨在托管在Tomcat上。

现在，根据以上信息，我决定将整个项目记录到三个不同的文档中：

1. 解释源代码等的文档。 2. 解释编译器设置、项目定义等所需文件和目录的目的的文档。 3. 解释部署目录结构的文档。

或者，我可以创建一个单一文档，其中包含解释上述1-3的三个部分。

现在，问题如下：

1. 这是正确的方法吗？ 2. 是否有其他方法学习或借鉴？ 3. 您能否为此方法添加任何其他建议等？

任何其他信息都将有用。

非常感谢！

- Nomad

3个回答

3

尝试使用Javadocs链接。如果有合理的规划，它将解决你上面提到的所有问题。

- omermuhammed

1

是的，Javadocs 是微观层面的文档。我也对描绘应用程序的更广泛画面感兴趣... - Nomad

0

一份解释源代码等的文档。

是的。请将读者视为试图熟悉项目编写原因（为什么创建此项目）以及项目的整体架构的人，并且源类上的Javadocs应该解释每个类的作用。您的文档应该像教程一样将Javadocs联系在一起。

一份解释编译器设置、项目定义等所需文件和目录目的的文档。

是的。

一份解释部署目录结构的文档。

我想这就是您的构建脚本所做的事情。也许我不理解您希望此文档实现的内容。

您能添加到这种方法中的其他建议吗？

除非这是您的开发组中任何人第一次记录Java项目，否则应该有其他文档。看看他们做了什么。

如果您是第一个，那么我会说这是一个很好的开始。我最感兴趣的是第一个文档。您的新程序员会喜欢第二个文档。

- Gilbert Le Blanc

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Soronthar · Accepted Answer

我认为你已经走在了正确的道路上。在一个项目中，您需要解决三个文档需求：

用户文档这包括一份说明应用程序是关于什么的文件，以及如何启动它/访问它。
开发文档这至少包括Javadocs、源代码目录结构描述、构建过程（即如何编译项目）、编译器时间依赖项、开发标准、如何设置数据库进行开发以及如何从存储库获取源代码。这些是您需要让其他人在您的项目中工作所需的最低限度。此外，随着项目复杂性的增加，我喜欢编写一系列“如何”文档，以处理系统中的常见任务（例如：“如何为给定操作留下审计跟踪”，“如何使用日志记录框架”，“如何管理异常”等），以及主要域类和它们之间的关系的描述。如果您使用数据库，并且数据库模式与域类不完全一对一，我将添加模式文档。
部署文档这基本上是应用程序的安装手册，描述使其运行所需的任何步骤：将WAR放入Tomcat中，针对数据库运行脚本，需要修改的配置文件等等。

如您所见，您已经部分解决了其中两个文档需求。从小做起，简单明了，随着需要的出现再逐步添加其他文档。

检查组织是否有任何文档标准也会有所帮助。