讓程序員早點下班的《技術寫作指南》
對于程序員來說,每天不是在寫bug,就是在修bug~
在不停coding之外,做好一些細節(jié)毋庸置疑也可以幫助我們早點下班。
這不,國外一位前端開發(fā)就總結了一篇《程序員技術寫作指南》,關于如何正確寫代碼注釋、寫PR描述等等。
這些東西雖然都是小事兒,但如果大家都不規(guī)范,代碼維護起來有多痛苦?
懂得都懂。
那么,具體都要注意些什么呢?
程序員技術寫作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)反常用法一定要注釋
有時,你為了進行一些兼容各種瀏覽器等目的,可能會在代碼中加入一些不常規(guī)的寫法。這時就一定要注意寫注釋。
不然別人可能一看覺得“這寫得啥”,唰地就給你改過來了……
例子:
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;
}
這里插播一點,指南提到:
不管寫什么,盡量多用主動語態(tài),因為正常人看到被動語態(tài)的句子時都需要在腦子里轉成主動語態(tài),沒必要增加這種處理時間。
(4)貼解決方案的鏈接
有時你遇到問題去網上搜到了解決辦法,那么可以把鏈接附上,方便回查,以防萬一。
有網友就表示這條建議非常有用,因為有時他就會忘記自己當時為什么要這么寫代碼。
2、PR描述
提交代碼時怎么寫PR描述也是一個重要的細節(jié),關乎到代碼審查的效率。
雖說很多團隊內部都有規(guī)范,但有人就是不怎么遵守。
下面這幾點尤其需要注意:
(1)寫詳細,不要寫“添加補丁”、“修復錯誤”這種模糊的表述;
正面例子:
eg1.支持NgOptimizedImage中的自定義srcset屬性
eg2.為所有內置ControlValueAccessors添加顯式選擇器
(2)不要一氣提交上千行代碼,盡量完成一小部分就提交,減輕評審壓力。
3、報告bug
需要提交錯誤報告時,盡量:
(1)多用截圖/動圖來輔助文本描述問題;
(2)提供重現(xiàn)問題的精確步驟;
(3)提供你分析的可能的原因。
4、Microcopy
ps.對于國內情況的話,本部分內容更適合產品經理食用。
Microcopy指的是用戶操作/系統(tǒng)出現(xiàn)失誤時,你的網頁/APP彈出的提示語。
這種提示語怎么寫,也有講究:
(1)避免使用技術名詞。
相信很多人都遇到過彈出來一行你看不懂的技術提示語的時候,比如“執(zhí)行超時“這種,讓你不知道發(fā)生了什么,不知道該怎么做。
要避免這種情況,最好是不解釋出現(xiàn)了什么錯誤,直接告訴用戶該做什么。
(2)不要“責怪”用戶。
想象一下,你打開一個網站,進行登陸,然后被告知:“您的電子郵件/密碼不正確?!?br>
這種表達方式會讓人下意識地覺得不舒服,讓用戶覺得自己“很傻”。
正確方式:
“抱歉,電子郵件密碼組合不正確。我們可以幫助您恢復您的帳戶?!?br>
還有一點:盡量避免字母全部大寫或者使用感嘆號,會帶來敵意。
(3)恰當使用幽默語氣,有時強迫幽默比不幽默效果更糟糕。
原指南中還包括一些如何跟客戶溝通的建議,歡迎感興趣的朋友戳鏈接去閱讀~
最后,關于程序員技術寫作,你還有補充嗎?
參考鏈接:
https://css-tricks.com/technical-writing-for-developers/#writing-code-comments
作者:量子位
歡迎關注微信公眾號 :深圳灣碼農