不要強迫用英文撰寫你的程式註釋、文件

不曉得從什麼時候開始,有部分的開源社群(朋友間與社交網路)在推薦使用英文撰寫註解。這是沒什麼啦⋯⋯不過最靠北的不外乎朋友之間共同撰寫專案,還用破英文啊啊啊啊啊——。

不得不承認使用英文確實很 🅱️🅰️🆖。能讓整個專案的說明、文件看起來風格統一,而且又能夠跨國際讓網路上的其他人得知相關使用方式。但事實上,這不是一個習慣。

團隊敘述有差異

如果你正在一個團隊工作,試著使用你們最擅長的語言進行溝通,而不是強迫使用英文撰寫註釋、API 文件,否則這可能導致混淆還有稱呼習慣產生問題。

例如不少人會將 MD5 稱呼為「加密」,結果寫成英文的時候就直接寫成了:Encryption。

英文型態有障礙

不少人英文只學到一半就開始在程式裡用上,反倒容易令人變成尼哥問號。在「如何优雅的给代码写英文注释?」問答中,裡面有個留言值得參考。

我见过2B的代码,get的过去分词用getted,write的过去分词用writed。很多函数名里面主动被动语态都没分清,叫其他人怎么读代码。

效率低略,適得其反

使用英文容易讓你需要花費更多心思在如何正確地描述一件事物上,有些時候反倒會表述的含糊不清,最終卻僅寫出大略而非詳細的說明。舉例來說:

// Bite 會接收一個名字,並且偵測到是北韓人時,就會放狗咬他。
func Bite(name string) {  
    // ...
}

如果採用英文撰寫,不少人需要花費一些時間去思考語句的排序問題、單字、時態。感覺好浪費時間喔。不如就簡單說明一下就好了!

// Bite bites a North Korean.
func Bite(name string) {  
    // ...
}

請記得,正確地使用你最擅長的語言不僅能提升工作效率,還可以提高說明的精準度

無法從中提升英文技能

有些人推薦用英文撰寫註釋主要是你可以從中獲取到不少知識、增進英文技能。事實上卻不盡然。因為你只會用上你懂的單字而已,搭配 Google 的話效率又很低。

為了解決這個問題,我會推薦你試著看 YouTube 中文字幕影片時,順道打開英文自動字幕,這能夠更有效地幫助你學習。

有些時候英文自動字幕不是很好,或許看看今年被罵到爆的陰屍路第八季會好上更多(還有原文呢)。

程式只會越變越糟

讓我們來面對一個問題,也許是程式命名習慣很糟所以才需要一堆註釋。姑息養奸,再這麼下去猛寫註釋也不是辦法。程式界有種說法:

程式本身就是一種註釋。

程式本應被撰寫的一清二楚,清晰且有條理。在 Stackoverflow 上亦有不少人使用「虛擬程式碼」來相互溝通、並解決問題。我自己本身有個俄羅斯朋友,他看不懂中文,但是因為函式的英文命名跟使用方式都寫得很清晰,他現在用得很快樂(好有成就感)。

明確地撰寫程式流程、範例、命名才是解決問題的根本之道。順帶一提,如果你的變數名稱叫做 OwO 或是 var1 這種不明不楚的命名方式,你就該下地獄了。

如果真要用上英文,請謹記原則

部分 Linux 會在終端機開啟文件時對中文顯示有一定的困難(雖然我會直接換個終端機),或有些程式編譯會爬代而被迫需要使用英文撰寫所有事物,在這裡謹記:

註釋是用來敘述「為什麼」和「用途」,而不是「這個函式正在做什麼」。

雖然說寫中文也會有相同問題就是了。