豐色 發自 凹非寺
量子位 | 公眾號 QbitAI
對於程式設計師來說，每天不是在寫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）恰當使用幽默語氣，有時強迫幽默比不幽默效果更糟糕。
原指南中還包括一些如何跟客戶溝通的建議，歡迎感興趣的朋友戳連結去閱讀～
最後，關於程式設計師技術寫作，你還有補充嗎？