这是一个创建于 1056 天前的主题，其中的信息可能已经有所发展或是发生改变。
背景：我司的文档都是写接口文档，没看见过什么技术细节实现文档。本人写 java 。
疑问：大佬们的公司有要求写项目功能的技术实现细节文档吗？有的话可以给个参考吗？实在是找不到类似的参考。
举例：一个 controller 层，里面的 service 层可能包含几个小方法，应该怎么去写清楚？目的就是想着怎么让别人看得明明白白。
补充：本人目前在写一些个人的项目，但是无项目细节实现文档的编写经验，特请教 V 站的大佬。有链接请直接甩，感谢感谢。
第 1 条附言 · 2022-01-29 09:07:59 +08:00
问题背景：我司就是扔一个项目过来叫我照着进行二次开发，但文档什么的都没有，就只有 swaager 接口文档，注释也少，业务只能口头问负责人，因此产生了上述疑问。
吐槽：一个做了 n 个月的项目，经历了 n 波人，然后叫我根据这个 shit 项目用三天时间快速开发出一个小功能。。。各位元芳怎么看？
吐槽：一个做了 n 个月的项目，经历了 n 波人，然后叫我根据这个 shit 项目用三天时间快速开发出一个小功能。。。各位元芳怎么看？
 |
1
dajj 2022-01-28 13:26:19 +08:00  1
代码即文档。
UE4 引擎几十 G 的源代码也没技术文档。 |
 |
2
yurong333333 OP @dajj 无效回复。请尽量让自己的回复能够对别人有帮助，感谢。
|
|
3
yurong333333 OP 4
@dajj 比较有趣的是，您之前也有过类似的提问。https://www.v2ex.com/t/529611#reply0
|
 |
4
Jtyczc 2022-01-28 14:00:23 +08:00
没有，需求每个星期都不一样，能做完算不错了。
几百个需求还等着我。。。 |
|
5
yurong333333 OP @Jtyczc 唉。期待其他大佬有干货回答。
|
 |
6
charmToby 2022-01-28 14:05:47 +08:00
我的想法是注释上写参考项目 readme.md xxx 模块实现(详细介绍区域块可以折叠)，概述实现思路以及想法，可以图文并茂。但是多了，就怕代码迭代什么的忘了维护，久而久之就没啥用了。
|
 |
7
K1W1 2022-01-28 14:12:31 +08:00
除了文字说明外，我主要是流程图、序列图，再加上表结构设计，有些地方可能还会附上伪代码跟大致的 sql 语句
|
 |
8
Zchary 2022-01-28 14:13:33 +08:00 1
我们比较复杂的需求 Leader 都会经需求文档起草一份 RFC ，具体编写可以参照[RFC style guide]( https://www.rfc-editor.org/rfc/rfc7322)
|
 |
9
Sixyuan 2022-01-28 14:22:36 +08:00
感觉画图会比较清晰，主干是流程图，穿插一些图例和注释，特别需要阐述的再分段。
|
|
10
yurong333333 OP @charmToby 感谢回复，有帮助。
|
|
11
yurong333333 OP @K1W1 感谢回复，有帮助。
|
|
12
yurong333333 OP @Zchary 感谢回复，有帮助。
|
|
13
yurong333333 OP @Sixyuan 感谢回复，有帮助。
|
 |
14
declandragon 2022-01-28 15:53:59 +08:00
个人认为主要是流程图和产品说明文档吧。以前见过别人写的一个具体功能点的黑箱白箱对比文档，左边写实现的具体业务，右边写查询了哪个表哪个表，非常细节；这种文档不具有普适性，太耗时了。
|
 |
15
janus77 2022-01-28 15:59:33 +08:00 via iPhone
业务流程图，架构分层图，这种比较重要，然后针对各个小方法，感觉就直接用这个方法上面的注释就行了
|
 |
16
blackshow 2022-01-28 16:16:08 +08:00
C4 模型建议了解一下
|
 |
17
RainCats 2022-01-28 16:17:32 +08:00
强制要求代码里面写注释，做好代码审查。
别听什么好的代码不需要注释，当赶时间或者一大坨一大坨代码的时候你还有心思一行行代码读过去？ |
 |
18
javapythongo 2022-01-28 16:33:06 +08:00
没写过技术细节实现文档，只写过技术设计文档，主要包含对业务的理解、流程图、模型设计、数据库设计、功能拆分等
|
|
19
yurong333333 OP @RainCats 是的，项目赶的时候，好的注释能帮助节省不少时间。
|
|
20
yurong333333 OP @janus77 好的，感谢
|
|
21
yurong333333 OP @blackshow 好滴，这就去看，感谢。
|
 |
22
corningsun 2022-01-28 17:07:39 +08:00
描述 service 类有几个方法，一点意义都没有，而且这个不就是 java doc 的功能？
描述清楚关键业务的实现逻辑才是必要的，可以综合考虑用各类 UML 图，比如：架构图、时序图、状态图等。 |
|
23
yurong333333 OP @corningsun 前一句话觉得您可能没看清楚我表达的意思。但后一句话您又确实回答了问题。感谢。
|
 |
24
lidlesseye11 2022-01-28 18:39:46 +08:00
可以写一些要点。比如
参数的要求 有什么全局变量（是否线程安全） 主要的处理逻辑（判断，循环） 是否用了比较复杂的数据结构 是否涉及多线程 是否有数据库等中间件的 crud 可能抛出哪些异常 打了哪些 log 有哪些监控 要写的详细的话，日企有个 review 流程叫塗り潰す 就是左手文档右手代码，文档里看一句涂掉一句，代码里涂掉相关的行。 最后 review 完，文档和代码全都是涂掉的，一句不多一句不少。 可以说是非常工匠精神了 |
 |
25
2NUT 2022-01-28 19:16:54 +08:00 1
一楼的回复是有价值的，直接被你无效了
你说的那种是项目经理写的，不属于一般非技术经理程序员的职责范畴 |
|
26
yurong333333 OP @lidlesseye11 学习了，感谢您的回复。
|
 |
27
SteveWoo 2022-01-29 00:46:14 +08:00
写文档的话，先想清楚写这个文档的目的（给谁看，对方的知识水平如何，读者需要提前具备哪些基础知识，期望对方看了能收获哪些内容），基于以上写好文档的背景和意义。
接下来就围绕目的，慢慢的撸了（除非用于技术评审，其不用纠结文笔，专业术语哪些玩意），能让具备前置条件的人看懂就行了。 |
|
28
yurong333333 OP @SteveWoo 主要是给那些完全没接触过该项目的人看，假设该读者的工作经验为一年及其以上，希望读者能够通过我的文档能够快速了解该项目的全局，并对该项目能够进行快速上手和二次开发。
|
|
29
SteveWoo 2022-02-08 15:24:48 +08:00
@yurong333333 解该项目的全局 和 二次开发 之间有点矛盾了。
快速上手和二次开发建议放弃文档介绍，工作了这些就要自己去啃代码，找人请教业务，不要主动去教。 建议重点写，全局概览，和你了解的业务流程。 1. 先介绍负责的块属于公司哪个产品线或者中台主要服务哪些，有什么价值。 2. 重点画个大图，介绍自己负责的那些模块接口，是做什么，相互是否关联，上下游游用户是谁，责任人是谁，有问题可以找谁。 这些都可以用方框+线条搞定了。 3. 其后，把自己熟悉的业务，业务流程介绍清楚，也可以用方框+线条，然后简单的说明涉及到哪些模块（这里不要写太详细，职业的打工人应该自己去啃，不需要保姆教学） |
Select Language