程序员如何高效和同行交流

你是否在工作中经常遇到这种对话：

A：你给我的接口为啥访问不通啊？

B：确定是 POST 方法吗？参数 foo 加了吗？

A：加了啊？

B：我看下。

5分钟后。

B：你没加 application/json 啊。

A：还是访问不通啊。

B：我看下。

5分钟后。

B：URL 后面不能加 / 啊，不需要加。

A：……

B：……

本文介绍一些如何避免这种无意义的对话的方法。个人认为，写在简历里面的“沟通能力强”并不是一个软技能，而是一个硬技能。不是说话啰嗦，敬词用的多就是沟通能力强，而是用最少的话把信息描述清楚没有歧义，这要求理智和健全的身心，以及相关的工具和背景知识。

---

糟糕的沟通：紧张的描述 “我的 xxx 怎么不 xxx？”  “xxx 了怎么办？” 别人很难回答你的问题，必须继续追问你几个回合之后才知道你想表达什么。

有效的沟通：以不让别人追问为原则，描述清楚自己遇到的问题，所处的运行环境，如何复现。能够让别人复现你的场景非常重要。举个例子，前端的问题可以用 jsfiddle 复现，后端问题可以提供一个 docker 命令。

另外，报告问题的时候，最好能简洁清晰的证明问题。比如，我们提供了一个 HTTP 接口，用户如果报告这个接口的问题，最简单直观的方法就是发一个 cURL 命令，阐明预期的返回是什么，但是现在的返回是什么。很多人在报告问题的时候用的是截图、他们自己代码的日志，问题是，我们无法知道你的代码怎么写的，无法判断这个问题是你的代码造成的还是我们的服务造成的。所以最好的方式，就是使用一个第三方的工具，清楚得表明做的事情和目前的现象。

---

糟糕的沟通：截图一大片代码，中间包含某个报错。并问：为啥我的命令的结果是这样？

有效的沟通：贴出来这个命令一个结果的文字版本，然后提问。

除非是 GUI 方面的问题，一般人都会憎恨从图片中抄写代码。贴 URL 、代码以及转发，要优于贴图片。

如果一些 IM 工具对代码的格式化不好，（比如微信和钉钉），可以将代码写到 Gist 然后贴 Gist 的链接。甚至传文件也比截图要强。

有时候你要将别的群聊内容转发给另一个对象的话，尽量使用 IM 的转发功能，这样别人就可以知道上下文，知道前因后果。如果公司特别大，你经常遇到去问一个人A，A甩手让你去问B，B又让你问C的话，转发功能就比较好用了。

无论是在网络论坛，还是聊天，亦或是邮件，都应该善用引用能，提供原文的地址要优于复述原文。

粘贴命令行的文本的时候（通常是日志），要带上生成这些文本的命令。因为光看到这些结果，别人不知道这些结果代表什么意思，是怎么来的。但是如果带上了 grep example.com access.log ，这样的命令，不必描述，别人就可以理解文本代表什么含义了。

如果实在要截图的话，也要尽量带上原始的命令，不要只截取结果。

---

糟糕的沟通：文档中写：接口参数是xxx，URL是xxx。

不要指望你这么描述能够让一个 HTTP 接口没有歧义。更糟糕的是，我见过 HTTP 的文档上就贴了一个 Java 的 Class，并且里面的注释类似这样： private String button; // 按钮

有效的沟通：在写文档或者 IM 工具中，尽量用 cURL 或 HAR 交流参数信息。如果是 HTTP API 文档，在有条件的情况下，可以搭建像 Swagger 这样的 API 平台。向接口的提供方描述问题的时候，不要说我使用的xxx怎么不行？可以直接贴给对方你的 cURL 命令，这样它们就知道你发送的请求了。现代的浏览器，以及 postman insomnia 这种 API 工具，都支持将 HTTP 请求导出到 cURL。

除了 HTTP，其他的交流也可以使用命令。比如遇到磁盘问题，可以将 df 或者 mount 命令之类的作为信息提供给运维同事。命令优于口头描述。

---

糟糕的沟通：在吗？

有效的沟通：直接提供你的问题，尽可能描述对方可能用到的所有的信息，不让别人追问。

这一条尤为重要，否则可能会被同事当做神经病。

---