怎么写项目细节实现文档?

2022-01-28 11:19:38 +08:00
 yurong333333

背景:我司的文档都是写接口文档,没看见过什么技术细节实现文档。本人写 java 。

疑问:大佬们的公司有要求写项目功能的技术实现细节文档吗?有的话可以给个参考吗?实在是找不到类似的参考。

举例:一个 controller 层,里面的 service 层可能包含几个小方法,应该怎么去写清楚?目的就是想着怎么让别人看得明明白白。

补充:本人目前在写一些个人的项目,但是无项目细节实现文档的编写经验,特请教 V 站的大佬。有链接请直接甩,感谢感谢。

2770 次点击
所在节点    问与答
29 条回复
dajj
2022-01-28 13:26:19 +08:00
代码即文档。
UE4 引擎几十 G 的源代码也没技术文档。
yurong333333
2022-01-28 13:41:49 +08:00
@dajj 无效回复。请尽量让自己的回复能够对别人有帮助,感谢。
yurong333333
2022-01-28 13:43:11 +08:00
@dajj 比较有趣的是,您之前也有过类似的提问。https://www.v2ex.com/t/529611#reply0
Jtyczc
2022-01-28 14:00:23 +08:00
没有,需求每个星期都不一样,能做完算不错了。

几百个需求还等着我。。。
yurong333333
2022-01-28 14:02:00 +08:00
@Jtyczc 唉。期待其他大佬有干货回答。
charmToby
2022-01-28 14:05:47 +08:00
我的想法是注释上写参考项目 readme.md xxx 模块实现(详细介绍区域块可以折叠),概述实现思路以及想法,可以图文并茂。但是多了,就怕代码迭代什么的忘了维护,久而久之就没啥用了。
K1W1
2022-01-28 14:12:31 +08:00
除了文字说明外,我主要是流程图、序列图,再加上表结构设计,有些地方可能还会附上伪代码跟大致的 sql 语句
Zchary
2022-01-28 14:13:33 +08:00
我们比较复杂的需求 Leader 都会经需求文档起草一份 RFC ,具体编写可以参照[RFC style guide]( https://www.rfc-editor.org/rfc/rfc7322)
Sixyuan
2022-01-28 14:22:36 +08:00
感觉画图会比较清晰,主干是流程图,穿插一些图例和注释,特别需要阐述的再分段。
yurong333333
2022-01-28 15:39:32 +08:00
@charmToby 感谢回复,有帮助。
yurong333333
2022-01-28 15:39:41 +08:00
@K1W1 感谢回复,有帮助。
yurong333333
2022-01-28 15:39:50 +08:00
@Zchary 感谢回复,有帮助。
yurong333333
2022-01-28 15:39:57 +08:00
@Sixyuan 感谢回复,有帮助。
declandragon
2022-01-28 15:53:59 +08:00
个人认为主要是流程图和产品说明文档吧。以前见过别人写的一个具体功能点的黑箱白箱对比文档,左边写实现的具体业务,右边写查询了哪个表哪个表,非常细节;这种文档不具有普适性,太耗时了。
janus77
2022-01-28 15:59:33 +08:00
业务流程图,架构分层图,这种比较重要,然后针对各个小方法,感觉就直接用这个方法上面的注释就行了
blackshow
2022-01-28 16:16:08 +08:00
C4 模型建议了解一下
RainCats
2022-01-28 16:17:32 +08:00
强制要求代码里面写注释,做好代码审查。
别听什么好的代码不需要注释,当赶时间或者一大坨一大坨代码的时候你还有心思一行行代码读过去?
javapythongo
2022-01-28 16:33:06 +08:00
没写过技术细节实现文档,只写过技术设计文档,主要包含对业务的理解、流程图、模型设计、数据库设计、功能拆分等
yurong333333
2022-01-28 16:39:07 +08:00
@RainCats 是的,项目赶的时候,好的注释能帮助节省不少时间。
yurong333333
2022-01-28 16:39:19 +08:00
@janus77 好的,感谢

这是一个专为移动设备优化的页面(即为了让你能够在 Google 搜索结果里秒开这个页面),如果你希望参与 V2EX 社区的讨论,你可以继续到 V2EX 上打开本讨论主题的完整版本。

https://www.v2ex.com/t/831078

V2EX 是创意工作者们的社区,是一个分享自己正在做的有趣事物、交流想法,可以遇见新朋友甚至新机会的地方。

V2EX is a community of developers, designers and creative people.

© 2021 V2EX