让程序员早点下班的《技术写作指南》

↑ 点击 蓝字  关注极市平台

来源丨量子位

编辑丨极市平台

极市导读

 

国外一位前端开发就总结了一篇《程序员技术写作指南》，关于如何正确写代码注释、写PR描述等等。 >>加入极市CV技术交流群，走在计算机视觉的最前沿

对于程序员来说，每天不是在写bug，就是在修bug～

在不停coding之外，做好一些细节毋庸置疑也可以帮助我们早点下班。

这不，国外一位前端开发就总结了一篇《程序员技术写作指南》，关于如何正确写代码注释、写PR描述等等。

这些东西虽然都是小事儿，但如果大家都不规范，代码维护起来有多痛苦？

懂得都懂。

那么，具体都要注意些什么呢？

程序员技术写作Tips

1、代码注释

代码注释既是写给自己看，也是写给别人看的。尤其是后者，更要写得清楚明了。

对此，指南给了三点注意：

（1）写关键信息，不写废话

一个简单的例子。

错误写法：

red = 1.2 // Multiply red by 1.2 and re-assign it（将red变量2，再赋值给它）

正确写法：

red *= 1.2 // Apply a ‘reddish’ effect to the image（给图像应用“reddish”效果）

很好理解。不要复述代码，要写这段代码的深层含义，提供增量信息。

（2）代码改动后注释也要更新

有这样一行代码和注释：

cities = sortWords(cities) // sort cities from A to Z（由A-Z排序城市变量）

但作者写错了，其实sortWords函数是从Z-A进行排序。

不过没关系，再加个反转就好了，于是代码变成这样：

cities = sortWords(cities) // sort cities from A to Z（由A-Z排序城市变量）
cities = reverse(cities)

然后问题就来了，别人不知道这个过程，只看到第一行的注释，会自然以为城市是先按A-Z进行排，然后再反过来从Z排到A。

这就是改了代码不改注释的后果。

当然，这个例子是被放大了。但类似事情确实有可能造成不必要的麻烦。

（3）反常用法一定要注释

有时，你为了进行一些兼容各种浏览器等目的，可能会在代码中加入一些不常规的写法。这时就一定要注意写注释。

不然别人可能一看觉得“这写得啥”，唰地就给你改过来了……

例子：

function addSetEntry(set, value) {
/ Don’t return set.add because it’s not chainable in IE 11. （不要返回“set.add”，它跟IE 11不兼容）/
set.add(value);
return set;
}

这里插播一点，指南提到：

不管写什么，尽量多用主动语态，因为正常人看到被动语态的句子时都需要在脑子里转成主动语态，没必要增加这种处理时间。

（4）贴解决方案的链接

有时你遇到问题去网上搜到了解决办法，那么可以把链接附上，方便回查，以防万一。

有网友就表示这条建议非常有用，因为有时他就会忘记自己当时为什么要这么写代码。

2、PR描述

提交代码时怎么写PR描述也是一个重要的细节，关乎到代码审查的效率。

虽说很多团队内部都有规范，但有人就是不怎么遵守。

下面这几点尤其需要注意：

（1）写详细，不要写“添加补丁”、“修复错误”这种模糊的表述；

正面例子：

eg1.支持NgOptimizedImage中的自定义srcset属性

eg2.为所有内置ControlValueAccessors添加显式选择器

（2）不要一气提交上千行代码，尽量完成一小部分就提交，减轻评审压力。

3、报告bug

需要提交错误报告时，尽量：

（1）多用截图/动图来辅助文本描述问题；

（2）提供重现问题的精确步骤；

（3）提供你分析的可能的原因。

4、Microcopy

ps.对于国内情况的话，本部分内容更适合产品经理食用。

Microcopy指的是用户操作/系统出现失误时，你的网页/APP弹出的提示语。

这种提示语怎么写，也有讲究：

（1）避免使用技术名词。

相信很多人都遇到过弹出来一行你看不懂的技术提示语的时候，比如“执行超时“这种，让你不知道发生了什么，不知道该怎么做。

要避免这种情况，最好是不解释出现了什么错误，直接告诉用户该做什么。

（2）不要“责怪”用户。

想象一下，你打开一个网站，进行登陆，然后被告知：“您的电子邮件/密码不正确。”

这种表达方式会让人下意识地觉得不舒服，让用户觉得自己“很傻”。

正确方式：

“抱歉，电子邮件密码组合不正确。我们可以帮助您恢复您的帐户。”

还有一点：尽量避免字母全部大写或者使用感叹号，会带来敌意。

（3）恰当使用幽默语气，有时强迫幽默比不幽默效果更糟糕。

原指南中还包括一些如何跟客户沟通的建议，欢迎感兴趣的朋友戳链接去阅读～

最后，关于程序员技术写作，你还有补充吗？

参考链接：
https://css-tricks.com/technical-writing-for-developers/#writing-code-comments

公众号后台回复“项目实践”获取50+CV项目实践机会～

△点击卡片关注极市平台，获取 最新CV干货

极市干货

最新数据集资源 ： 医学图像开源数据集汇总（二）

技术解读 ：一文打尽NMS技术的种种｜这是一篇对YOLOv7的详细解读和剖析

极视角动态： 青岛日报专访｜极视角陈振杰：创业的每一个决定都要经得起逻辑推演 ｜ 启动报名｜2022GCVC全球人工智能视觉产业与技术大会，7月22日青岛见！

# 极市原创作者激励计划 #

极市平台深耕CV开发者领域近5年，拥有一大批优质CV开发者受众，覆盖微信、知乎、B站、微博等多个渠道。通过极市平台，您的文章的观点和看法能分享至更多CV开发者，既能体现文章的价值，又能让文章在视觉圈内得到更大程度上的推广。

对于优质内容开发者，极市可推荐至国内优秀出版社合作出书，同时为开发者引荐行业大牛，组织个人分享交流会，推荐名企就业机会，打造个人品牌 IP。

投稿须知：

1. 作者保证投稿作品为自己的 原创作品。

2. 极市平台尊重原作者署名权，并支付相应稿费。文章发布后，版权仍属于原作者。

3.原作者可以将文章发在其他平台的个人账号，但需要在文章顶部标明首发于极市平台

投稿方式：

添加小编微信Fengcall（微信号：fengcall19），备注：姓名-投稿

△长按添加极市平台小编

“

点击阅读原文进入CV社区

收获更多技术干货