讓程序員早點(diǎn)下班的《技術(shù)寫(xiě)作指南》

對(duì)于程序員來(lái)說(shuō)，每天不是在寫(xiě)bug，就是在修bug～

在不停coding之外，做好一些細(xì)節(jié)毋庸置疑也可以幫助我們?cè)琰c(diǎn)下班。

這不，國(guó)外一位前端開(kāi)發(fā)就總結(jié)了一篇《程序員技術(shù)寫(xiě)作指南》，關(guān)于如何正確寫(xiě)代碼注釋、寫(xiě)PR描述等等。

這些東西雖然都是小事兒，但如果大家都不規(guī)范，代碼維護(hù)起來(lái)有多痛苦？

懂得都懂。

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

程序員技術(shù)寫(xiě)作Tips
1、代碼注釋
代碼注釋既是寫(xiě)給自己看，也是寫(xiě)給別人看的。尤其是后者，更要寫(xiě)得清楚明了。

對(duì)此，指南給了三點(diǎn)注意：

（1）寫(xiě)關(guān)鍵信息，不寫(xiě)廢話

一個(gè)簡(jiǎn)單的例子。

錯(cuò)誤寫(xiě)法：

red = 1.2 // Multiply red by 1.2 and re-assign it（將red變量2，再賦值給它）
正確寫(xiě)法：

red *= 1.2 // Apply a ‘reddish’ effect to the image（給圖像應(yīng)用“reddish”效果）
很好理解。不要復(fù)述代碼，要寫(xiě)這段代碼的深層含義，提供增量信息。

（2）代碼改動(dòng)后注釋也要更新

有這樣一行代碼和注釋：

cities = sortWords(cities) // sort cities from A to Z（由A-Z排序城市變量）
但作者寫(xiě)錯(cuò)了，其實(shí)sortWords函數(shù)是從Z-A進(jìn)行排序。

不過(guò)沒(méi)關(guān)系，再加個(gè)反轉(zhuǎn)就好了，于是代碼變成這樣：

cities = sortWords(cities) // sort cities from A to Z（由A-Z排序城市變量）
cities = reverse(cities)
然后問(wèn)題就來(lái)了，別人不知道這個(gè)過(guò)程，只看到第一行的注釋，會(huì)自然以為城市是先按A-Z進(jìn)行排，然后再反過(guò)來(lái)從Z排到A。

這就是改了代碼不改注釋的后果。

當(dāng)然，這個(gè)例子是被放大了。但類似事情確實(shí)有可能造成不必要的麻煩。

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

有時(shí)，你為了進(jìn)行一些兼容各種瀏覽器等目的，可能會(huì)在代碼中加入一些不常規(guī)的寫(xiě)法。這時(shí)就一定要注意寫(xiě)注釋。

不然別人可能一看覺(jué)得“這寫(xiě)得啥”，唰地就給你改過(guò)來(lái)了……


例子：

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;
}
這里插播一點(diǎn)，指南提到：

不管寫(xiě)什么，盡量多用主動(dòng)語(yǔ)態(tài)，因?yàn)檎Ｈ丝吹奖粍?dòng)語(yǔ)態(tài)的句子時(shí)都需要在腦子里轉(zhuǎn)成主動(dòng)語(yǔ)態(tài)，沒(méi)必要增加這種處理時(shí)間。

（4）貼解決方案的鏈接

有時(shí)你遇到問(wèn)題去網(wǎng)上搜到了解決辦法，那么可以把鏈接附上，方便回查，以防萬(wàn)一。

有網(wǎng)友就表示這條建議非常有用，因?yàn)橛袝r(shí)他就會(huì)忘記自己當(dāng)時(shí)為什么要這么寫(xiě)代碼。



2、PR描述
提交代碼時(shí)怎么寫(xiě)PR描述也是一個(gè)重要的細(xì)節(jié)，關(guān)乎到代碼審查的效率。

雖說(shuō)很多團(tuán)隊(duì)內(nèi)部都有規(guī)范，但有人就是不怎么遵守。

下面這幾點(diǎn)尤其需要注意：

（1）寫(xiě)詳細(xì)，不要寫(xiě)“添加補(bǔ)丁”、“修復(fù)錯(cuò)誤”這種模糊的表述；

正面例子：






eg1.支持NgOptimizedImage中的自定義srcset屬性

eg2.為所有內(nèi)置ControlValueAccessors添加顯式選擇器

（2）不要一氣提交上千行代碼，盡量完成一小部分就提交，減輕評(píng)審壓力。

3、報(bào)告bug
需要提交錯(cuò)誤報(bào)告時(shí)，盡量：

（1）多用截圖/動(dòng)圖來(lái)輔助文本描述問(wèn)題；

（2）提供重現(xiàn)問(wèn)題的精確步驟；

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

4、Microcopy
ps.對(duì)于國(guó)內(nèi)情況的話，本部分內(nèi)容更適合產(chǎn)品經(jīng)理食用。

Microcopy指的是用戶操作/系統(tǒng)出現(xiàn)失誤時(shí)，你的網(wǎng)頁(yè)/APP彈出的提示語(yǔ)。

這種提示語(yǔ)怎么寫(xiě)，也有講究：

（1）避免使用技術(shù)名詞。

相信很多人都遇到過(guò)彈出來(lái)一行你看不懂的技術(shù)提示語(yǔ)的時(shí)候，比如“執(zhí)行超時(shí)“這種，讓你不知道發(fā)生了什么，不知道該怎么做。

要避免這種情況，最好是不解釋出現(xiàn)了什么錯(cuò)誤，直接告訴用戶該做什么。

（2）不要“責(zé)怪”用戶。

想象一下，你打開(kāi)一個(gè)網(wǎng)站，進(jìn)行登陸，然后被告知：“您的電子郵件/密碼不正確?！?br>
這種表達(dá)方式會(huì)讓人下意識(shí)地覺(jué)得不舒服，讓用戶覺(jué)得自己“很傻”。

正確方式：

“抱歉，電子郵件密碼組合不正確。我們可以幫助您恢復(fù)您的帳戶?！?br>
還有一點(diǎn)：盡量避免字母全部大寫(xiě)或者使用感嘆號(hào)，會(huì)帶來(lái)敵意。

（3）恰當(dāng)使用幽默語(yǔ)氣，有時(shí)強(qiáng)迫幽默比不幽默效果更糟糕。

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

最后，關(guān)于程序員技術(shù)寫(xiě)作，你還有補(bǔ)充嗎？

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








作者：量子位


歡迎關(guān)注微信公眾號(hào) ：深圳灣碼農(nóng)