對于程序員來說，每天不是在寫 bug，就是在修 bug～

在不停 coding 之外，做好一些細節毋庸置疑也可以幫助我們早點下班。

這不，國外一位前端開發就總結了一篇《程序員技術寫作指南》，關于如何正確寫代碼注釋、寫 PR 描述等等。

這些東西雖然都是小事兒，但如果大家都不規范，代碼維護起來有多痛苦？

懂得都懂。

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

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）恰當使用幽默語氣，有時強迫幽默比不幽默效果更糟糕。

原指南中還包括一些如何跟客戶溝通的建議，歡迎感興趣的朋友戳鏈接去閱讀～

最后，關于程序員技術寫作，你還有補充嗎？