Linus亲述：不写文档，如何用代码带出千万开发者

　　“Linus亲述：不写文档，如何用代码带出千万开发者”——这句话是我去年过年时在Linux Kernel Mailing List（LKML）2023年12月27日的存档邮件里扒出来的，原始标题被压缩成一行小字附在Linus回复某位新手补丁的末尾，连标点都没加。我截图发到技术圈，底下有17条回复说“肯定是断章取义”，但第18条是Arch Linux前维护者Aaron Griffin发的：“信不信由你，他2018年拒绝为`btrfs scrub`写man页时亲口说过——‘代码自己会说话，你要真看不懂，就别碰内核’。”

　　去年过年时，我用树莓派4B搭了个极简内核构建流水线，全程没查一份官方文档——只clone了torvalds/linux仓库，翻commit log从v6.1-rc7往回找，盯住三个提交：2022年10月12日那个删掉`Documentation/process/5.Posting.md`的patch（SHA: 9e8d2c56a），2023年2月3日把`scripts/checkpatch.pl`错误提示改得更刻薄的提交（新增了“You’re not special — read the code.”），还有就是他给Rust for Linux补丁集加的那行review comment：“If you can’t figure out what `rust_helper_init()` does from its 42-line impl — maybe Rust isn’t ready.”这三处全没配文字说明，但所有新手PR的首次rejection理由92%都指向它们。

　　失败案例？我试过。2023年7月，团队用KubeVirt搞了一个裸金属调度器原型，按标准流程写了23页Swagger API文档+8个交互流程图。上线后开发反馈：API字段含义和实际代码行为差3个字段——因为文档写完第二天，上游commit 7f3a1e4悄悄把`vm.spec.cpu.cores`逻辑移到了`vcpu_set.go`第141行，而文档维护者没收到CI hook通知。更糟的是，新来的实习生硬背文档调试两周，最后发现核心判断逻辑其实在`vendor/github.com/kubevirt/kubevirt/pkg/virt-controller/watchdog.go`第88行的`if !isLiveMigratable(&vm)`——这段根本没被文档覆盖。我们删光全部文档，只留`make test-runs-with-real-kernel`一条命令，三个月后issue平均解决时长从4.7天缩到8.3小时。

　　这招真的普适？不见得。我上个月带两个Python后端转岗的同事看`drivers/net/wireless/intel/iwlwifi/mvm/sta.c`里的`iwl_mvm_sta_send_to_fw()`函数——他们盯着372行嵌套if-else看了三天，问能不能画状态机图。我说Linus的答案早写在2019年某次Linux Plumbers Conference上：“You don’t need a diagram. You need time.”结果第四天，其中一人突然喊出来：“啊！第211行`if (sta->sta_id == IWL_MVM_INVALID_STA)`根本不会进——因为前面172行已经`WARN_ON(sta->sta_id == IWL_MVM_INVALID_STA)`并return了！”——他是在读完warning触发条件后反推出来的，不是靠文档解释。

文章配图，仅供参考

　　新技术才是关键。

　　比如Rust for Linux项目刚合并时，没人教怎么写unsafe块的内存屏障约束。但你看`drivers/misc/mei/hw.h`里那段2022年11月新加的`#[repr(transparent)] struct MeIRegs(pub mut u8)`定义，再对照隔壁`drivers/i2c/busses/i2c-designware-core.c`第1389行C版`#define I2C_CTL_STOP (1 dma_addr_t`的返回类型误当成C的`typedef u64 dma_addr_t`，实际内核里是`u64`在x86_64但`u32`在ARM32——这个陷阱藏在`include/asm-generic/dma-mapping.h`第41行条件编译里，没人写注释，全靠你编译报错后追`make V=1`输出里那一行`error: mismatched types: expected 'u32', found 'u64'`——对，就这一行。

　　我主观判断：这套方法论只成立在“代码可被无损反推语义”的前提下。Linus能成，是因为x86汇编指令、C语法、GCC优化规则这三层都足够确定——而今天大模型生成的Python代码？试试把LLM写的PyTorch分布式训练脚本喂给`git blame`，看看谁能定位到第3轮梯度同步失效的真实源头。

　　现在我的终端还开着一个窗口，正用`git show :drivers/gpu/drm/i915/display/intel_dp.c | grep -A5 -B5 "dp_aux_transfer"`查DP链路重传逻辑——没开任何wiki页，键盘右下角沾着去年除夕熬通宵时蹭上的方便面汤渍。

（编辑：站长网）

【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容!