如题，新手前端，感觉前端的大部分文档有大段地文字介绍也有 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
 |
1
lrvy 5 天前
你看的部分是接口和结构体定义。可以找一下有无 example 或测试用例，比如 go-git 在问当中就有 https://pkg.go.dev/github.com/go-git/go-git/v5#readme-examples
|
 |
2
dobelee 5 天前
一般不看这玩意，直接看包的文档。标准库的直接在 IDE 看。
|
 |
3
lscho 5 天前  4
不是 go 文档要比前端文档难懂，是后端比前端文档难懂
go 作为函数式编程、低语法糖，已经是后端里文档最容易写最容易看懂的语言之一了 |
 |
4
zhengfan2016 OP @lrvy 但是 go git 提供的两个 example 属于 get starter 级别的，我想找那种读取特定仓库特定时间段 commit 的 func ，好像还是得去结构体定义里找
|
 |
5
cmdOptionKana 5 天前
你给出的三种文档都不同项目……
你找一个小学生写的英语文章，再找一个著名作家写的汉语文章，然后问为什么汉语写的文章特别优秀？ 文档都是人写的，和写文章一模一样，水平高就写得好，反而与“语言”的关系不大。 |
 |
6
BeautifulSoap 5 天前 via Android 11
不要怀疑，大部分 go 的文档（包括官方文档）都写得依托狗屎，对于第一次看相关功能或者想要深入了解的人来说没多大参考价值。写得晦涩难懂七零八散，最要命的是功能都写不全。很多关键功能文档里都不会写的，你只能去看别人代码怎么用或特意去搜才知道
用了多年 Go ，我的建议是你要快速了解一个包或者内置包怎么用，直接谷歌关键字搜别人写的文章或问 ai 就行 |
 |
7
hailaz 5 天前
我觉得主要是因为 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 |
|
8
cmdOptionKana 5 天前 2
首先 go-git 本身就不是按 Go 语言思维从零开始做的项目，它要模仿 git ，把原本用 C 语言写的项目翻译为 Go ，这种“翻译”类型的项目多数情况下都要求你原本就对 C 语言版的 git 比较熟悉。
|
|
9
hailaz 5 天前
作为框架对比，可以看看 https://goframe.org/ ，虽然写的不一定很好，但起码够用了。
|
 |
10
kekeabab 5 天前
其实就是文档烂，三言两语带过，有些文档还不如函数方法名字长，作用全靠看名字猜，能懂就怪了。
go 很多文档根本没法看，很多根本就没有文档，全靠 example 、test 、自己全都试一遍。 |
 |
11
dwu8555 5 天前
把文档给 AI ，让 AI 帮你就行了
|
 |
12
wangtian2020 5 天前 1
前端面向过程编程是这样的，你想做什么文档就教你怎么做。
后端面向对象这种思维就是废话多，就像是你想吃饭非得教你读菜单起锅烧炉结果菜单上的字不认识。 |
 |
13
njutree 5 天前
这不是 GO 的问题是项目的问题，前端项目之所以文档好一些还是因为风格和习惯的问题
|
 |
14
sky3hao 5 天前
好家伙, 什么叫"比前端还难懂"
前端在后端眼里就是个高级 UI |
 |
15
mightybruce 5 天前
难道不都是看 *_test.go 和 examples 吗， 不要太指望开源项目的文档。
|
 |
16
MoYi123 5 天前
react 的是人写的.
go 的这个文档是通过代码里的注释直接生成的, 我从来不看这玩意. |
 |
17
pkoukk 5 天前
我入行是写 C#的，我甚至不知道写代码要看文档，想知道这个函数干啥的，IDE 点一下跳到源码看看结构看看注释就懂了
后面写 node js ，才发现原来这种语言离开了互联网就一个字也写不动，没文档根本不知道有什么函数和方法 现在写 go ，找回了一大半 C#的感觉吧，基本上不太需要看网页文档，跳源码看注释就行 |
 |
18
Vegetable 5 天前
go 这圈子里文档相关做的就是不好的。基于注释生成文档这个路线走歪了，很多包的作者选择不做友好的文档，真就用注释当文档。
|
|
19
cmdOptionKana 4 天前
@Vegetable 基于注释生成文档是很正常的路线吧？很多语言都有这个做法。
|
 |
20
ns09005264 4 天前 1
我觉得 Rust 标准库的文档写的非常好，说明清晰，几乎都有示例。光看 LSP 的 Hover 提示就知道怎么用了。
|
 |
21
iyear 4 天前
因为 go 本身基于注释的文档不好用(Rust 的就好很多有高亮有补全)，所以开发者都不太喜欢在注释里写，基本都在 repo README 里。go.dev 我一般都是拿来还没用的时候看一下整体结构啥的
|
 |
24
RayR 4 天前
@BeautifulSoap 深以为然。文档上的基本没有结构、详尽的用法。即使是标准库上的注释（虽然已经很长了）也得不可避免地一层层点下去看怎么实现的。
|
 |
25
qxdo1234 4 天前
封装的好的 api 一般在文档里会有 examples ，并且你看 go test 也可以看个大概的用法。我觉得是 go 本身语法简单，所以知道某个库的用途，大概看方法的参数和逻辑，就可以知道了。
|
 |
26
SingeeKing 4 天前 1
Go 的文档在一定程度上混淆了 Doc 和 Reference ；虽然叫 godoc ，但是更多的还是以 reference 存在的
相比之下 Rust 就好很多 —— 虽然 doc 和 reference 还是融合在一起的，但是专门为 doc 做了非常多的优化 |
|
27
SingeeKing 4 天前
另外，同等比较的话，应该是用 typedoc 来比？而不是用 React 自己的文档站……
|
 |
28
y332332 4 天前
之前我就奇怪 demo 不仅数量少，而且有些贴一大段找不到重点。后来看了源码才发现，demo 是从 test 文件里抄的，就是测试代码。太会偷懒了。
|
 |
29
flyqie 4 天前 2
确实难懂，很多 go 项目其实跟#26 说的一样，doc 跟 reference 是混淆的。
不习惯的话确实非常难受，没办法，go 的许多项目就这样。 习惯了的话其实也还凑合，进一个项目先翻 example 和 tests 就能找到大概用法了。 |
 |
30
superchijinpeng 4 天前
@sky3hao 不是吧，哥们
|
 |
31
GeekGao 4 天前
关键问题是：examples 太少了。如果像 PHP 文档那样，就不会有这个主题了。
|
 |
32
vituralfuture 4 天前 via Android
C++库的文档更烂，要么又臭又长，要么非常短，想用明白?自己看源码去吧
|
 |
33
memorycancel 4 天前
老传统了。RTFM 。。。
|
 |
34
noyidoit 4 天前
确实不好，Go 生态很多文档的很多方法都是一句话带过，文档额外提供的信息跟函数名差不多，稍微深入一点就要搜索、问 ai 、源码+playground"白盒测试"
|
 |
35
snowlyg 4 天前
go 还要看文档吗？不都是看源码吗
|
 |
36
aloxaf 4 天前
是的，Go 文档颇有上世纪风格，在 21 世纪还这么设计，除了故意折磨用户之外我想不出其他理由了。
随便举几个例子： 1. 一眼望去基本就三种颜色，黑色的背景、白色的文字、蓝色的链接，毫无区分度 2. 代码连语法高亮都不给 3. ToC 这种东西放在开头毫无意义，单纯挤占正常阅读空间 4. 边上可以全部展开的导航栏又不展开，到这里又开始省空间了？ 5. 搜索界面跟 GPT2 设计的一样，仿佛没学过布局，而且鼠标移上去下划线是竟然是出现在类型上？？ 6. 不能跨模块搜索 我觉得这玩意儿能气死 UX 设计师 |
 |
37
encro 4 天前
因为你看的：
一个是 doc ！ 另外一个是代码注释！ 一个是写文档的时候特别写的，一个是写代码是顺便写的。 你应该问： 问什么多 go 项目没有专门文档(doc)，那么回答可能是因为 easy ，看数据结构就行。 |
|
38
encro 4 天前
而且你看的不是一个级别东西。
react 是一个主要面向开发者的库，专注的是开发体验。 request 也是一个开发库，专注开发体验。 这两个东西需要文档。。。 git 包大部分代码专注于数据结构和流程，体验在命令行接口那块。 |
 |
39
wzy44944 4 天前 1
正常，就是前后端熟练程度不一样。我是后端，看前端的文档觉得更费劲，后端不管文档写得怎么样，可以直接翻看源码，单步调试来理解，前端因为对运行机制不熟悉，调试，源码这个依赖路径不太灵了就
|
 |
40
bingfengfeifei 4 天前
因为前端和 Python 的文档是人写的，Go 的是直接代码的接口生成的。
前面的有样例，而且 Go 的和看代码没区别 |
 |
41
lanisle 4 天前
在我看来，是因为前端的领域（ UI ）本来就比较难快速上手，轮子多，不同轮子的造法不同，用法（思维）又不一样，加上各家有各家的细节，肯定要写多一些才让人能懂。另外前端竞争大，文档写好一些，争取多一些用户。
后端的从业者，基础可以的话，尤其是本科科班出生，换一门语言上手的曲线还是不陡的，除非换了一种编程范式，但这不是文档能解决的事。 |
 |
42
seth19960929 4 天前
go doc 的默认文档就是一坨屎, 根本就不是文档.
|
 |
43
duli950523 4 天前
@lscho #3 我觉得同时代出的 rust 文档好多了，跟前端后端没关系，go 的文档就是很烂很简陋
|
 |
44
wen20 4 天前
感觉你期待的就教学文档。 适合全新入门。
go 列出来的是 “关键元素” 文档。 适合有一定了解。 适合的场景不一样吧。 |
 |
45
kios 4 天前
Go 的文档还算可以了，算比较简单易懂的了
|
 |
46
EricYuan1 4 天前 via iPhone
怎么前端都在卷 go ，俺也是在转 go 的路上哈哈
|
 |
47
me1onsoda 4 天前
后端编程语言，谁看文档。。要么看源码要么不看。react 文档真是业界楷模，是真怕你学不会
|
 |
48
cnbattle 4 天前 via Android
|
 |
49
lijiangang886 4 天前
#3 go 是函数式编程？我人麻了
|
 |
50
jqtmviyu 4 天前
|
|
51
jqtmviyu 4 天前
感觉都不如问 ai, 大部分给出的都像是代码注释自动生成的, 前端 ui 文档应该都是有手工维护的.
|
 |
52
Trim21 4 天前 via Android
@jqtmviyu 这个 Python 的文档也是从代码注释生成的，只不过 sphinx 比 godoc 的功能多多了，所以生成的文档效果好很多…
|
 |
53
abc612008 4 天前 1
@lscho 我第一次听说一个没有 map/filter/reduce/fold,没有 immutable,没有 sum type,没有 pattern matching,不支持 tail recursion optimization 的语言能叫函数式的
|
 |
54
FreeEx 4 天前
因为你发的 go 文档是自动生成的，其他俩是手写的。
|
 |
55
Track13 3 天前
要不你去看看 pixijs 的文档，还有 fabricjs 。全靠自己尝试。
|
 |
56
iseki 3 天前 via Android
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 然后描述空着似乎强了那么一些呢。 |
 |
57
bzj 3 天前
学 go 之前先学学 c 语言会比较好点
|
Select Language