程序员,你为什么不写文档?

你有没有遇到过这样的同事——每次问他问题，他口头给你解释得清清楚楚，但让他写下来，他就开始推脱：“这有什么好写的，代码就是最好的文档。”

你有没有见过这样的代码——变量名叫a、b、tmp，函数几百行，注释几乎为零。当你接手时，只能对着屏幕发呆，默默问候写这段代码的人。

你有没有经历过这样的项目——上线半年后，当初的设计者已经离职，留下的只有零散的聊天记录和几句口头禅：“我记得当时好像这么改过……”

如果你是程序员，你一定懂我在说什么。

写作，是程序员最被低估的技能。

今天，我们来聊聊程序员写作这件事。

一、为什么说写作是程序员的“第二语言”？

很多人认为，程序员的核心技能就是写代码。但真相是：优秀的代码需要被理解，而理解需要文字。

1. 写作锻炼逻辑思维

编程和写作，本质上是一回事——都是将复杂的思想，用清晰的结构表达出来。

写代码时，我们需要定义变量、设计函数、梳理流程。写文章时，我们需要确定主题、组织段落、层层递进。两者都在训练同一项核心能力：清晰思考。

一个能把复杂技术讲清楚的人，大概率也能把复杂代码写清楚。

2. 写作提升代码的可读性

你写的代码，不只是给机器看的，更是给人看的。

当你在写注释时，当你在写README时，当你在写接口文档时，你都在“写作”。优秀的文档能让维护者快速理解代码意图，大幅降低维护成本。

反过来想：如果一段代码连你自己一个月后都看不懂，那这段代码的质量真的好吗？

3. 写作促进团队协作

现在的软件开发，几乎没有单打独斗的英雄。

代码审查、技术方案讨论、需求沟通……每一项都依赖清晰的书面表达。GitHub上的评论、PR描述、技术文档，都是协作的基石。

一句话说不清楚的需求，往往是一万行bug的开始。

二、写作，是最好的学习方式

你可能听过这样一句话：“教是最好的学。”

写作，就是一种“教”的过程。

美国教育心理学家Bloom将知识认知分为六个层次：记忆、理解、应用、分析、评鉴、创造。单纯的阅读和听课，往往只停留在前两个层次。而当你试图把知识写下来时，你必须：

· 重新梳理知识的脉络

· 发现自己理解模糊的地方

· 查阅资料填补认知空白

· 用清晰的逻辑呈现出来

这个过程，会把知识真正“内化”成你自己的东西。

我自己就有这样的体会：很多技术点，我以为自己懂了，但当我试图写成文章时，才发现“原来这里我还没搞明白”。

写作，是对自己认知的“压力测试”。

三、程序员写作的三个层次

第一层：为自己写

写给自己看——技术笔记、问题记录、学习心得。

这是最容易开始的层次。不需要文采，不需要排版，只需要如实记录。当你遇到一个坑，把它记下来；当你解决一个bug，把过程写下来。

这些东西，是你未来最宝贵的“技术资产”。

第二层：为团队写

写给同事看——接口文档、设计文档、PR描述、代码注释。

这是职业素养的体现。一个“糟糕程序员”往往在这些细节上掉链子：

· 提交代码不写描述，或者写“fix bug”、“update”这种无意义的话

· 重要逻辑不写注释，或者注释写得拖沓难懂

· 接口协议全靠口头沟通，不给规范文档

· 重要设计不写文档，交接时只说“我记得……”

而优秀的程序员，会把文档当成代码一样重视。因为他们知道：一份清晰的文档，比100句口头解释更高效。

第三层：为世界写

写给所有人看——技术博客、开源文档、技术分享。

当你开始向外输出，你会收获意想不到的回报：

· 反馈：读者会指出你的错误，补充你不知道的信息

· 连接：你会认识志同道合的朋友，甚至获得工作机会

· 影响力：持续输出会让你在行业内建立个人品牌

很多人问我：“我水平一般，能写博客吗？”

我的回答永远是：能。

你不需要成为专家才能写作。把你学习新技术的坑、解决某个问题的过程记录下来，本身就是有价值的。这种“学习者的视角”，往往比专家的完美教程更能引起共鸣。

四、程序员写作的实用技巧

如果你已经动心，却不知道如何下笔，这里有一些实用的建议：

1. 从小处着手，别想一口吃成胖子

不要试图写“Java从入门到精通”，而是写“如何用Java实现一个简单的线程池”。聚焦一个具体的“小”问题，更容易写透，也更容易被有同样问题的读者搜索到。

2. 明确你的读者

写作前，先想清楚：这篇文章是写给谁看的？

· 给初级开发人员看？那就多解释基础概念，提供背景信息

· 给资深同行看？那就直奔主题，讲深讲透

· 给自己看？那怎么舒服怎么来

心中有读者，下笔才有方向。

3. 结构清晰，逻辑分明

好的文章就像好的代码：有清晰的结构，有明确的职责划分。

· 标题要抓人：想想“如何写出高性能SQL”和“让数据库快10倍的5个技巧”，哪个更吸引人？

· 开头要点题：用一两句话告诉读者，这篇文章能解决什么问题

· 段落要分明：每个段落只讲一个观点，用标题和列表组织内容

· 结尾要总结：回顾要点，引导下一步

4. 用简洁的语言，说清楚复杂的事

这是技术写作最难、也最重要的一点。

· 用主动语态：不要说“变量x被赋值为5”，而说“把5赋值给变量x”

· 避免长句：一个句子讲一件事，讲不清楚就拆成两句

· 解释术语：第一次提到缩写时，给出全称

· 用示例说话：一个具体的例子，胜过千言万语的抽象描述

William Zinsser在《写作技巧》中说得好：“写得好文章的秘诀，是将每个句子拆成最简洁的成分。”

5. 代码注释，要有信息增量

很多人写注释，只是在复述代码：

“`javascript

// 把red乘以1.2，再赋值给它

red *= 1.2

“`

这样的注释毫无意义。好的注释应该提供“代码之外的增量信息”：

“`javascript

// 给图像应用红色调效果

red *= 1.2

“` [citation:6]

**注释要回答“为什么”，而不是“是什么”。**

### 6. 注意那些“不起眼”的细节

很多时候，决定一篇文章质量的，是细节。

– 技术名词拼写要规范：Java，不是JAVA；JavaScript，不是javascript[citation:3][citation:9]

– 中英文之间加空格：让排版更舒服[citation:3][citation:9]

– 保持术语一致：一会儿说“Protocol Buffers”，一会儿说“Protobuffs”，会让读者困惑[citation:4]

这些细节，体现的是你对读者的尊重。

 五、如何克服“不敢写”的心理？

我知道你在想什么。

“我写得太差了，被人笑话怎么办？”

“我的水平不够，写出来误导人怎么办？”

“网上已经有很多人写过了，我还有必要写吗？”

让我告诉你三个真相：

**第一，没有人一开始就写得好。**

写作是手艺，需要练习。你的第一篇可能很烂，你的第十篇可能还不错，你的第五十篇可能就有人转发了。这是每个写作者必经的路[citation:8]。

**第二，你的“学习过程”本身就是价值。**

网上确实有很多“完美教程”，但它们往往跳过了那些坑坑洼洼的过程。而初学者最需要的，恰恰是“如何一步步走过来”的真实记录[citation:10]。

**第三，写不好，还写不坏吗？**

就算写坏了，又怎样？互联网很大，没几个人会盯着你的“烂文”不放。而你却通过写作，梳理了知识，锻炼了表达，这笔账怎么算都不亏。

## 六、开始写吧

关于写作，我想分享我最喜欢的一句话：

> “做你的第二稿，是让你看起来好像你一直在做自己知道的事情的过程。” —— Neil Gaiman[citation:7]

意思是：没有人一次写成，所有人都在修改中变好。

所以，不要追求完美。从今天开始，从一篇小文章开始，从记录一个你刚解决的问题开始。

– 创建一个博客，哪怕只是用Notion或Typora

– 把你今天踩的一个坑写下来

– 把你刚学会的一个小技巧分享出去

– 把你对某个技术的理解整理成文

**写作，是程序员性价比最高的投资。**

它让你的知识更扎实，让你的表达更清晰，让你的影响力更大，让你的职业道路更宽。

开始写吧。

哪怕只有一个读者——那个读者就是未来的你自己。

*你在写作中遇到过什么困难？或者有什么写作心得？欢迎在评论区分享。*