讓程序員早點下班的《技術(shù)寫作指南》
代碼注釋不規(guī)范，就是給人找麻煩
豐色 發(fā)自 凹非寺
量子位 | 公眾號 QbitAI
對于程序員來說，每天不是在寫bug，就是在修bug～
在不停coding之外，做好一些細節(jié)毋庸置疑也可以幫助我們早點下班。
這不，國外一位前端開發(fā)就總結(jié)了一篇《程序員技術(shù)寫作指南》，關(guān)于如何正確寫代碼注釋、寫PR描述等等。
這些東西雖然都是小事兒，但如果大家都不規(guī)范，代碼維護起來有多痛苦？
懂得都懂。
那么，具體都要注意些什么呢？
程序員技術(shù)寫作Tips
1、代碼注釋
代碼注釋既是寫給自己看，也是寫給別人看的。尤其是后者，更要寫得清楚明了。
對此，指南給了三點注意：
（1）寫關(guān)鍵信息，不寫廢話
一個簡單的例子。
錯誤寫法：
red = 1.2 // Multiply red by 1.2 and re-assign it（將red變量2，再賦值給它）正確寫法：
red *= 1.2 // Apply a ‘reddish’ effect to the image（給圖像應(yīng)用“reddish”效果）很好理解。不要復述代碼，要寫這段代碼的深層含義，提供增量信息。
（2）代碼改動后注釋也要更新
有這樣一行代碼和注釋：
cities = sortWords(cities) // sort cities from A to Z（由A-Z排序城市變量）但作者寫錯了，其實sortWords函數(shù)是從Z-A進行排序。
不過沒關(guān)系，再加個反轉(zhuǎn)就好了，于是代碼變成這樣：
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)的句子時都需要在腦子里轉(zhuǎn)成主動語態(tài)，沒必要增加這種處理時間。
（4）貼解決方案的鏈接
有時你遇到問題去網(wǎng)上搜到了解決辦法，那么可以把鏈接附上，方便回查，以防萬一。
有網(wǎng)友就表示這條建議非常有用，因為有時他就會忘記自己當時為什么要這么寫代碼。
2、PR描述
提交代碼時怎么寫PR描述也是一個重要的細節(jié)，關(guān)乎到代碼審查的效率。
雖說很多團隊內(nèi)部都有規(guī)范，但有人就是不怎么遵守。
下面這幾點尤其需要注意：
（1）寫詳細，不要寫“添加補丁”、“修復錯誤”這種模糊的表述；
正面例子：
eg1.支持NgOptimizedImage中的自定義srcset屬性
eg2.為所有內(nèi)置ControlValueAccessors添加顯式選擇器
（2）不要一氣提交上千行代碼，盡量完成一小部分就提交，減輕評審壓力。
3、報告bug
需要提交錯誤報告時，盡量：
（1）多用截圖/動圖來輔助文本描述問題；
（2）提供重現(xiàn)問題的精確步驟；
（3）提供你分析的可能的原因。
4、Microcopy
ps.對于國內(nèi)情況的話，本部分內(nèi)容更適合產(chǎn)品經(jīng)理食用。
Microcopy指的是用戶操作/系統(tǒng)出現(xiàn)失誤時，你的網(wǎng)頁/APP彈出的提示語。
這種提示語怎么寫，也有講究：
（1）避免使用技術(shù)名詞。
相信很多人都遇到過彈出來一行你看不懂的技術(shù)提示語的時候，比如“執(zhí)行超時“這種，讓你不知道發(fā)生了什么，不知道該怎么做。
要避免這種情況，最好是不解釋出現(xiàn)了什么錯誤，直接告訴用戶該做什么。
（2）不要“責怪”用戶。
想象一下，你打開一個網(wǎng)站，進行登陸，然后被告知：“您的電子郵件/密碼不正確。”
這種表達方式會讓人下意識地覺得不舒服，讓用戶覺得自己“很傻”。
正確方式：
“抱歉，電子郵件密碼組合不正確。我們可以幫助您恢復您的帳戶。”
還有一點：盡量避免字母全部大寫或者使用感嘆號，會帶來敵意。
（3）恰當使用幽默語氣，有時強迫幽默比不幽默效果更糟糕。
原指南中還包括一些如何跟客戶溝通的建議，歡迎感興趣的朋友戳鏈接去閱讀～
最后，關(guān)于程序員技術(shù)寫作，你還有補充嗎？
參考鏈接：
https://css-tricks.com/technical-writing-for-developers/#writing-code-comments
- 北大開源最強aiXcoder-7B代碼大模型！聚焦真實開發(fā)場景，專為企業(yè)私有部署設(shè)計2024-04-09
- 剛剛，圖靈獎揭曉！史上首位數(shù)學和計算機最高獎“雙料王”出現(xiàn)了2024-04-10
- 8.3K Stars!《多模態(tài)大語言模型綜述》重大升級2024-04-10
- 谷歌最強大模型免費開放了！長音頻理解功能獨一份，100萬上下文敞開用2024-04-10
相關(guān)閱讀
AI向程序員老司機學習：從眼神變化中尋找bug
NAIST的研究人員把眼球追蹤的研究用在軟件開發(fā)領(lǐng)域，讓智能體從程序員的眼部活動中學習找bug、打補丁、寫注釋。
