大佬们，为什么我感觉 go 文档要比前端文档难懂

[zhengfan2016]

如题，新手前端，感觉前端的大部分文档有大段地文字介绍也有 demo 代码，很好理解。但是 go 的大部分文档看着有点像 ts 定义，文档介绍每个方法也没有提供 demo 供参考。是我的食用方法不对吗？

前端的文档： https://react.dev/reference/react/useInsertionEffect
go 的文档： https://pkg.go.dev/github.com/go-git/go-git/v5#RestoreOptions
python 的文档： https://requests.readthedocs.io/en/latest/user/advanced/#keep-alive

[lrvy]

你看的部分是接口和结构体定义。可以找一下有无 example 或测试用例，比如 go-git 在问当中就有 https://pkg.go.dev/github.com/go-git/go-git/v5#readme-examples

[dobelee]

一般不看这玩意，直接看包的文档。标准库的直接在 IDE 看。

[lscho]

不是 go 文档要比前端文档难懂，是后端比前端文档难懂

go 作为函数式编程、低语法糖，已经是后端里文档最容易写最容易看懂的语言之一了

[zhengfan2016]

@lrvy 但是 go git 提供的两个 example 属于 get starter 级别的，我想找那种读取特定仓库特定时间段 commit 的 func ，好像还是得去结构体定义里找

[cmdOptionKana]

你给出的三种文档都不同项目……

你找一个小学生写的英语文章，再找一个著名作家写的汉语文章，然后问为什么汉语写的文章特别优秀？

文档都是人写的，和写文章一模一样，水平高就写得好，反而与“语言”的关系不大。

[BeautifulSoap]

不要怀疑，大部分 go 的文档（包括官方文档）都写得依托狗屎，对于第一次看相关功能或者想要深入了解的人来说没多大参考价值。写得晦涩难懂七零八散，最要命的是功能都写不全。很多关键功能文档里都不会写的，你只能去看别人代码怎么用或特意去搜才知道

用了多年 Go ，我的建议是你要快速了解一个包或者内置包怎么用，直接谷歌关键字搜别人写的文章或问 ai 就行

[hailaz]

我觉得主要是因为 go 以前没有统一文档，go docs 这么久了，也没有重视开发（ go.dev 才几年），也没有要求大家都要写。

各个 go 项目基本都是自己的文档，前端你要对比的话应该拿 https://www.npmjs.com/package/three 这种和 go 这个做对比更合适，其实都是需要另外找文档。

而 vue react 这些更多是独立的一个文档了，所以体验肯定比较好的。

我一般都是先到 git 主库上找文档的，例如你给到的项目 https://github.com/go-git/go-git/blob/master/_examples/README.md

[cmdOptionKana]

首先 go-git 本身就不是按 Go 语言思维从零开始做的项目，它要模仿 git ，把原本用 C 语言写的项目翻译为 Go ，这种“翻译”类型的项目多数情况下都要求你原本就对 C 语言版的 git 比较熟悉。

[hailaz]

作为框架对比，可以看看 https://goframe.org/ ，虽然写的不一定很好，但起码够用了。

[kekeabab]

其实就是文档烂，三言两语带过，有些文档还不如函数方法名字长，作用全靠看名字猜，能懂就怪了。

go 很多文档根本没法看，很多根本就没有文档，全靠 example 、test 、自己全都试一遍。

[dwu8555]

把文档给 AI ，让 AI 帮你就行了

[wangtian2020]

前端面向过程编程是这样的，你想做什么文档就教你怎么做。
后端面向对象这种思维就是废话多，就像是你想吃饭非得教你读菜单起锅烧炉结果菜单上的字不认识。

[njutree]

这不是 GO 的问题是项目的问题，前端项目之所以文档好一些还是因为风格和习惯的问题

[PUR4uF5Oq0z0YN9r]

好家伙, 什么叫"比前端还难懂"
前端在后端眼里就是个高级 UI

[mightybruce]

难道不都是看 *_test.go 和 examples 吗， 不要太指望开源项目的文档。

[MoYi123]

react 的是人写的.
go 的这个文档是通过代码里的注释直接生成的, 我从来不看这玩意.

[pkoukk]

我入行是写 C#的，我甚至不知道写代码要看文档，想知道这个函数干啥的，IDE 点一下跳到源码看看结构看看注释就懂了
后面写 node js ，才发现原来这种语言离开了互联网就一个字也写不动，没文档根本不知道有什么函数和方法
现在写 go ，找回了一大半 C#的感觉吧，基本上不太需要看网页文档，跳源码看注释就行

[Vegetable]

go 这圈子里文档相关做的就是不好的。基于注释生成文档这个路线走歪了，很多包的作者选择不做友好的文档，真就用注释当文档。

[cmdOptionKana]

@Vegetable 基于注释生成文档是很正常的路线吧？很多语言都有这个做法。

[ns09005264]

我觉得 Rust 标准库的文档写的非常好，说明清晰，几乎都有示例。光看 LSP 的 Hover 提示就知道怎么用了。

[iyear]

因为 go 本身基于注释的文档不好用(Rust 的就好很多有高亮有补全)，所以开发者都不太喜欢在注释里写，基本都在 repo README 里。go.dev 我一般都是拿来还没用的时候看一下整体结构啥的

[jeesk]

@pkoukk 点名批评 nodejs 文档，从来没见过如此敷衍的东西

[duhb]

@sky3hao #14 2025 年了，到现在还有这种狭隘思想存在的人。。。

[RayR]

@BeautifulSoap 深以为然。文档上的基本没有结构、详尽的用法。即使是标准库上的注释（虽然已经很长了）也得不可避免地一层层点下去看怎么实现的。

[qxdo1234]

封装的好的 api 一般在文档里会有 examples ，并且你看 go test 也可以看个大概的用法。我觉得是 go 本身语法简单，所以知道某个库的用途，大概看方法的参数和逻辑，就可以知道了。

[SingeeKing]

Go 的文档在一定程度上混淆了 Doc 和 Reference ；虽然叫 godoc ，但是更多的还是以 reference 存在的

相比之下 Rust 就好很多 —— 虽然 doc 和 reference 还是融合在一起的，但是专门为 doc 做了非常多的优化

[SingeeKing]

另外，同等比较的话，应该是用 typedoc 来比？而不是用 React 自己的文档站……

[y332332]

之前我就奇怪 demo 不仅数量少，而且有些贴一大段找不到重点。后来看了源码才发现，demo 是从 test 文件里抄的，就是测试代码。太会偷懒了。

[flyqie]

确实难懂，很多 go 项目其实跟#26 说的一样，doc 跟 reference 是混淆的。

不习惯的话确实非常难受，没办法，go 的许多项目就这样。

习惯了的话其实也还凑合，进一个项目先翻 example 和 tests 就能找到大概用法了。

[superchijinpeng]

@sky3hao 不是吧，哥们

[R4rvZ6agNVWr56V0]

关键问题是：examples 太少了。如果像 PHP 文档那样，就不会有这个主题了。

[vituralfuture]

C++库的文档更烂，要么又臭又长，要么非常短，想用明白?自己看源码去吧

[memorycancel]

老传统了。RTFM 。。。

[noyidoit]

确实不好，Go 生态很多文档的很多方法都是一句话带过，文档额外提供的信息跟函数名差不多，稍微深入一点就要搜索、问 ai 、源码+playground"白盒测试"

[snowlyg]

go 还要看文档吗？不都是看源码吗

[aloxaf]

是的，Go 文档颇有上世纪风格，在 21 世纪还这么设计，除了故意折磨用户之外我想不出其他理由了。

随便举几个例子：
1. 一眼望去基本就三种颜色，黑色的背景、白色的文字、蓝色的链接，毫无区分度
2. 代码连语法高亮都不给
3. ToC 这种东西放在开头毫无意义，单纯挤占正常阅读空间
4. 边上可以全部展开的导航栏又不展开，到这里又开始省空间了？
5. 搜索界面跟 GPT2 设计的一样，仿佛没学过布局，而且鼠标移上去下划线是竟然是出现在类型上？？
6. 不能跨模块搜索

我觉得这玩意儿能气死 UX 设计师

[encro]

因为你看的：

一个是 doc ！

另外一个是代码注释！

一个是写文档的时候特别写的，一个是写代码是顺便写的。


你应该问：

问什么多 go 项目没有专门文档(doc)，那么回答可能是因为 easy ，看数据结构就行。

[encro]

而且你看的不是一个级别东西。

react 是一个主要面向开发者的库，专注的是开发体验。
request 也是一个开发库，专注开发体验。

这两个东西需要文档。。。


git 包大部分代码专注于数据结构和流程，体验在命令行接口那块。

[wzy44944]

正常，就是前后端熟练程度不一样。我是后端，看前端的文档觉得更费劲，后端不管文档写得怎么样，可以直接翻看源码，单步调试来理解，前端因为对运行机制不熟悉，调试，源码这个依赖路径不太灵了就

[bingfengfeifei]

因为前端和 Python 的文档是人写的，Go 的是直接代码的接口生成的。
前面的有样例，而且 Go 的和看代码没区别

[lanisle]

在我看来，是因为前端的领域（ UI ）本来就比较难快速上手，轮子多，不同轮子的造法不同，用法（思维）又不一样，加上各家有各家的细节，肯定要写多一些才让人能懂。另外前端竞争大，文档写好一些，争取多一些用户。

后端的从业者，基础可以的话，尤其是本科科班出生，换一门语言上手的曲线还是不陡的，除非换了一种编程范式，但这不是文档能解决的事。

[SethShi]

go doc 的默认文档就是一坨屎, 根本就不是文档.

[duli950523]

@lscho #3 我觉得同时代出的 rust 文档好多了，跟前端后端没关系，go 的文档就是很烂很简陋

[wen20]

感觉你期待的就教学文档。 适合全新入门。
go 列出来的是 “关键元素” 文档。 适合有一定了解。

适合的场景不一样吧。

[devtk]

Go 的文档还算可以了，算比较简单易懂的了

[EricYuan1]

怎么前端都在卷 go ，俺也是在转 go 的路上哈哈

[me1onsoda]

后端编程语言，谁看文档。。要么看源码要么不看。react 文档真是业界楷模，是真怕你学不会

[cnbattle]

Go.dev 是代码文档，不是使用文档，另外两个是你给的是使用文档，不是一个维度的文档

所以使用 go 包时，找对应的包自己的使用文档或问 ai 0.0

[lijiangang886]

#3 go 是函数式编程？我人麻了

[jqtmviyu]

这是 transmissionrpc 的文档对比

官方: https://github.com/transmission/transmission/blob/main/docs/rpc-spec.md
go: https://pkg.go.dev/github.com/hekmon/transmissionrpc/v3
python: https://transmission-rpc.readthedocs.io/en/stable/

[jqtmviyu]

感觉都不如问 ai, 大部分给出的都像是代码注释自动生成的, 前端 ui 文档应该都是有手工维护的.

[Trim21]

@jqtmviyu 这个 Python 的文档也是从代码注释生成的，只不过 sphinx 比 godoc 的功能多多了，所以生成的文档效果好很多…

[abc612008]

@lscho 我第一次听说一个没有 map/filter/reduce/fold,没有 immutable,没有 sum type,没有 pattern matching,不支持 tail recursion optimization 的语言能叫函数式的

[FreeEx]

因为你发的 go 文档是自动生成的，其他俩是手写的。

[bgm004]

要不你去看看 pixijs 的文档，还有 fabricjs 。全靠自己尝试。

[iseki]

Go 的文档风格是极简风格的。它舍弃了比如 Java 语言的 javadoc ，使用带有特定语法格式的文本表达的格式化文档，使文档更容易编写。一般来说，以 Kotlin 举例，kdoc 需要这么写
```java
/**
* Title
*
* @param[foo] description for foo
* @param[bar] desc for bar
* @return blahblah...
*/

```
而 Go 则倾向于使用人类语言来描述：
FunctionName returns blahblah. The parameter foo is blah, the bar is ....

显而易见，Go 这种文档是更容易编写的。你不能只看到它阅读困难，它好写，人们可能就爱写，比 kdoc 写一堆 @param 然后描述空着似乎强了那么一些呢。

[bzj]

学 go 之前先学学 c 语言会比较好点