Java项目文档

Question

我需要记录一个Java项目。我是C#程序员和系统分析师。但我对Java还不熟悉。

我已经从SVN中签出了目录。

这些目录包括源目录、WEB和项目定义所需的其他文件、类路径等。

据我所知，这些文件本质上属于以下三种类型之一

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

该项目(与大多数Java项目一样)是一个基于Eclipse的项目，旨在托管在Tomcat上。

现在，提供上述信息，我决定将整个项目记录为三个不同的文档。

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

或者，我也可以创建一个单独的文档，其中有三个部分解释了上面的1-3节。

现在，问题

1. 这样做对吗？
2. 还有什么其他的方法可以借鉴或借鉴吗？
3. 有什么其他建议可以添加到这种方法中吗？

任何其他信息将是有用的。

提前一吨谢谢

Answer 1

我觉得你走在正确的轨道上。在一个项目中，您需要满足三个文档需求。

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

正如您所看到的，您已经部分解决了其中的两个问题。从小而简单开始，并在需要时添加其余部分。

它还有助于检查您的组织是否有任何文档标准。

Answer 2

试试爪哇链接。书面与适当的计划，它将解决您以上的所有要点。

Answer 3

解释源代码等的文件。

是。如果您的读者试图熟悉项目编写的原因(为什么创建了这个项目)，以及项目的总体架构，那么就可以这样做。

源类上的Javadocs应该解释每个类所做的事情。您的文档应该像教程一样将Javadocs连接在一起。

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

是。

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

我想你的构建脚本就是这么做的。也许我不明白你期望这个文档完成什么。

有什么其他建议可以添加到这种方法中吗？

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

如果你是第一个，那么我会说这是一个很好的开始。我最感兴趣的是第一份文件。您的新程序员希望获得第二个文档。