iT邦幫忙

7

寫註解的必要性?

學生的時候,老師強調code要加上註解。工作初期我也是這麼認為的,但到現在我開始動搖了。因為我的工作要改很多人的code,他們雖然也有註解,但還是很難懂。這種感覺就像一個人不會表達,就算他再多解釋好幾句話,還是聽得霧煞煞。

我現在的結論是,如果程式本身寫得好,不用註解也沒關係。架構清晰、邏輯分明,一眼望去就知道在做什麼。而類別、方法、變數一開始就妥善命名,根本不用看註解就知道意思了。只剩下少數特別情況才需要用註解加以說明。

反觀有的程式寫得莫名其妙。已經一行一行讀,也有註解,但心中還是充滿問號。更多的是為註解而註解,重複無意義的廢話,如下:

int sum; // sum of value

// get the name
String name = getName(id);

最後個人對中文註解比較有感,畢竟我們母語是中文,相當於替我們翻譯好。但看習慣程式的人沒差,以及某些公司或系統禁止中文註解。小弟菜雞,不曉得各位前輩們怎麼想?

看更多先前的討論...收起先前的討論...
testh iT邦新手 4 級 ‧ 2020-08-30 08:50:33 檢舉
+1
補覺鳴詩 iT邦研究生 3 級 ‧ 2020-08-30 14:41:00 檢舉
我猜一行程式也要加註解是要培養習慣問題吧
yabee5566 iT邦新手 5 級 ‧ 2020-08-30 22:51:06 檢舉
一行不是問題, 為了註解而註解才是問題, 工程師要懶, 只做需要的工作, 不要做多餘為了形式的事情
另外中文註解我建議是不要比較好, 除你你英文真的爛只看中國的技術文章, 不然我們寫程式是用英文, 你塞中文註解你的大腦會做一次context switch 中翻英, 思緒容易中斷, 拖慢速度, 還有可能遇到編碼的問題
oxox iT邦研究生 5 級 ‧ 2020-08-31 09:39:01 檢舉
XX年了,我還是會寫註解。但主要是紀錄需求者、需求目的。
或是where 的限制是因為需求造成,或是資料限制。
不然之後USER來揮或是自己忘記,會改來改去還達不到目的。
另外因為某些原因沒使用習慣的語法,也會註明一下。
ant1017 iT邦新手 3 級 ‧ 2020-08-31 14:52:09 檢舉
我是根據要得到的結果下註解,這個函數跑完,我希望產出什麼...
這個判斷式跑完得到0會是怎樣,1又會是怎樣,內部運算就不做註解了...
因為每個人的構思不同,解法也不同,我是根據流程圖的方式來下註解而已
10
minuso
iT邦新手 5 級 ‧ 2020-08-30 15:22:57
最佳解答

註解的目的是幫助接手維護的工程師,包含自己 (?) 快速了解程式目的。
注意這裡講的是工程師,不是對程式語法有疑問,甚至連 Domain 單字都還沒建立的人。

結論上來說,需要寫註解的程式段落很少
(像是正規表示式等,可參閱 Clean Code 書中的舉例),
比起怕麻煩就寫註解甚至無腦就寫,
更該思考的是能否調整命名重構程式使結構與邏輯清晰的展現。

Don't comment bad code - rewrite it.
by Brian W. Kernighan, P.J. Plaugher

請記得,註解既然寫在程式裡,也是需要維護的,否則必定發生註解騙人的情況,
那在 Code review 中會是非常無言的情境...
難道要 Tech Lead 花時間去追究上一個修改者,為甚麼沒有同時去維護某段註解嗎?
(而這類錯誤只會一再發生,不刪除註解則無法根治,追究也只是浪費時間)

最後,真要註解,語言的採用還是英文為好,省去閱讀者的轉換
(除非你是用什麼吾有一術。名之曰!@#$%^^&)


補充個,若有導入測試機制的話,測試程式就是最好的註解

請問為什麼測試程式就是最好的註解?

minuso iT邦新手 5 級 ‧ 2020-09-03 00:07:18 檢舉

單元測試來說,
每個需要寫測試的方法,都會寫出一至多個測試方法,每一個去測試一個情境

當然,每個測試方法都有名字規範就看各個團隊去制定,像是

test[MethodName]Should[ResultName]When[ConditionName]() {...}

[MethodName]Should[ResultName]When[ConditionName]() {...}

when[ConditionName]Test[MethodName]Should[ResultName]() {...}

// ...

當測試完善時,我們就可以透過測試程式的名字了解被測試方法會需要驗證那些情境 (Condition -> Result)。

反過來說,這些不就正好是被測試方法需要實現的邏輯了嗎?
而且還是根據情境條列式的,比起註解的英文段落更加易讀好懂且真實。

這就是最好的註解 (易讀/真實)。

所以以單元測試來說,那些有被測試到的方法,完全不應該再用註解去解釋程式目的,那只會造成混淆 (來自英文段落理解能力差異的混淆) 與維護上的困難 (註解騙人/需要額外維護註解)。

6
舜~
iT邦高手 1 級 ‧ 2020-08-29 13:59:20

菜雞+1
以下我的想法

只要5年後的你回頭看時還看的懂你當年在寫什麼就不用註解了

有時候在開發的時候因為只專注某個片段,
註解通常也只會針對這個片段的當下動作進行註解~

但函數是個黑箱子,
箱子內每一步註解再多,
不如告知這個箱子是在做什麼的,
這我覺得相對比較重要~~

我現在的結論是,如果程式本身寫得好,不用註解也沒關係。架構清晰、邏輯分明,一眼望去就知道在做什麼。而類別、方法、變數一開始就妥善命名,根本不用看註解就知道意思了。只剩下少數特別情況才需要用註解加以說明。

其實您自己應該有結論了

4
Darwin Watterson
iT邦研究生 4 級 ‧ 2020-08-29 14:11:29

https://ithelp.ithome.com.tw/upload/images/20200829/20109107dO3lwOOlCP.png
導入git版控後,要求commit message寫清楚點,其實規格修改的註解可以少寫很多甚至不寫。
不過一些『自己找到的參考』拼出來的 code 還是註明一下出處(官網api就不必了)。
至於自己所獨創的演算法,當然一定要註解說明一下,不然未來一定會失傳/images/emoticon/emoticon20.gif

6
米歐
iT邦新手 4 級 ‧ 2020-08-29 14:19:39

我認為如果程式碼簡單到一眼就看的出來寫的人想表達的,那註解就不是必要的。

註解可以幫助我們在閱讀一份程式碼時,更快的理解撰寫者的用意,如果他不是亂寫的話。

通常是複雜邏輯,需要看一段時間才能搞懂程式碼在寫什麼,那麼註解可以幫助我們加快理解速度;或者是規範上的需求,例如這個變數為什麼在這裡會是這個值,在那裡又是另一個值,讓看的人不需要再去翻規範。

7
海綿寶寶
iT邦大神 1 級 ‧ 2020-08-29 14:22:22
註解可能會說謊(與現況不符)
但程式碼不會

真的!!!!

3
richardsuma
iT邦大師 1 級 ‧ 2020-08-29 23:48:32

我只會在程式開始寫註解,大概寫這隻程式的功能、日期、編修原因、要求編修的人,影響的範圍。
另外在函數的起頭寫註解,及特殊段落與語法會特別註記。

註解除了要讓自己快速了解這個程式結構外,還有方便後面接替維護的人員,這是寫註解的人要注意的,所以寫註解除了自己要能看得懂外,如何能讓人能夠讀得懂註解,這才是真功夫。

不是只會寫程式才厲害,能夠讓人透過註解來解讀並修改你的程式,才是真正厲害的人。

2
vicentli
iT邦新手 3 級 ‧ 2020-08-30 10:40:13

PG常覺得寫的func包含細部邏輯都很容易理解,所以不寫註解,
但不要太高估別人理解能力

你覺得很好懂,但code自己寫的當然好懂,我也覺得我寫得很超直白容易理解
但資深同事還是會來問我,還要花時間跟他解釋及拿範例出來,那我註解就好啦

所以我是習慣寫註解,不論該func或較特別邏輯運算時,方便自己金魚腦以後還看得懂
(當然一些雞毛蒜皮沒什麼特別需要理解就不寫了)

公司幾個厲害的資深同事,在接手對方程式碼時,都得問 ㄟ,你這段共用邏輯在寫什麼
儘管知道func在做什麼,但裡面的邏輯運算在做什麼就得花不少時間理解再拿來應用
時間寶貴,註解只花一點點時間,看別人code難一點的地方沒註解
最後浪費自己時間,也浪費第3、4、5個人來問的時間

最可怕是接手外包開發進來的code沒註解就真的吐血

sx0800 iT邦新手 5 級 ‧ 2020-08-30 12:11:35 檢舉

+1
「架構清晰、邏輯分明,一眼望去就知道在做什麼。」 自己覺得清晰不代表看的人也覺得清晰,寫幾句 funtion 的功能較好,免得一個月後自己也不知當時在寫什麼。
不過我這2年不寫註解了,年輕小主管說那是廢話,「碼」就是註解,和樓主一樣的自負。

我不是自負啦 ><
我講的不是我的code,是別人的code...

8
I code so I am
iT邦研究生 4 級 ‧ 2020-08-30 17:19:13

我是程式註解的信徒,程式要容易被理解的關鍵如下:

  1. 註解要像劇本一樣,主程式寫大綱,之後每隔一段程式註解該段的功能,最高段是只看註解,不看程式碼就可以初步理解程式的流程。
  2. 變數不要使用縮寫,並且至少要用兩個單字命名,例如,有人命名為id,我就會問是甚麼id,customer id or order id?
  3. 程式結構要像一隻蚊子,主程式要短,呼叫次功能,次功能再呼叫公用函數庫,形狀就會像一隻蚊子(系統設計書形容的,不是我發明的),只要看主程式,就可以知道大流程。

總之,註解與程式碼要相輔相成,才能成就大業啦!

欣賞先生菩薩的條理與縝密,追蹤先生了。感恩感恩 南無阿彌陀佛

fongyi iT邦新手 5 級 ‧ 2020-09-04 03:22:38 檢舉

好奇蚊子比喻的出處 ><

這是在校時讀的一本 System Design 的教科書,應該已經絕版,找不到了。系統分析與設計 快被世界遺忘了。

4
yabee5566
iT邦新手 5 級 ‧ 2020-08-30 22:44:31

去看Clean code那本書吧
答案大師早就講了

簡單的說註解不要重複描述程式碼本身,要寫的是程式碼本身以外的"意圖", "情境"
因為程式碼會因為時間修改, 但註解不影響程式運作, 所以很容易造成註解過時誤導開發者, 但意圖與情境不容易改變.

我寫註解的時候會是類似下面這幾個時間點

  1. 這裡寫法明顯跟其他地方不一樣, 是不是因為沒時間的workaround? 還是sdk特殊bug要避掉?
  2. 這個class大概在幹嘛?
  3. 命名盡量不縮寫以防看不懂, 縮寫會在後面補敘述縮寫的全文, 冷門的英文幫寫中文解釋
  4. 運算類似long threshold = time / (60 * 1000) // convert millis to min

一般來說, 以英文程度有一定水準的, 開發稍有心得的, 盡量要求自己不要寫註解, 當你想寫註解的時候, 通常是代表你的程式碼髒了, 需要refactor了, 因為邏輯架構不清楚所以自己才會想寫註解, 去把程式碼改好

而英文程度不好的人, 菜比八, 我個人是建議想寫註解就寫沒關係, 雖然註解有過時詞不達意的問題, 但你英文太差了, 程度太爛了, 本來程式碼就很難懂, 要refactor又做不到, 還他媽自以為高手都不寫, 那會搞慘更多人, 如果覺得自己都快看不懂又沒時間讓你refactor, 那就寫吧!等之後慢慢有點心得的時候在要求自己, 先求有再求好

yabee5566 iT邦新手 5 級 ‧ 2020-08-31 21:49:47 檢舉

補充一下好了, 之前我離職的時候交接, 主管習慣寫, 看我沒寫註解問我這是什麼意思? 我只是把function name再唸一次給他聽, 他就懂了. 程式碼及註解, 要盡量讓自己能做到這樣

這就是我的意思,註解只是把name插入空白...

1
fuzzylee1688
iT邦新手 1 級 ‧ 2020-08-31 08:45:34

在敏捷式開發過程, 我是先寫註解, 後寫code的.

3
sam0407
iT邦高手 1 級 ‧ 2020-08-31 10:12:25

寫註解這件事,我的看法用"見山是山,見山不是山,見山還是山"來說明

第一階段初入行,見山是山,聽人家說要寫註解,很認真的寫註解,也很認真的讀前輩寫的註解,但還是不能體會寫註解真正意義

第二階段工作一段時間,見山不是山,覺得寫註解沒什麼用,索性就不寫了,別人寫的亂七八糟也不想看

第三階段共同開發的經驗多或當主管了,見山還是山,吃盡了別人/自已註解寫不好,甚至根本就不寫註解的苦,菜鳥又不停的來問問題,這時候您會發現註解的重要,於是您把自己的經驗總結,訂定團隊註解的規範,成為程式開發團隊中的領頭羊~~

所以我的看法是,註解是一定要寫,而且是要有規範的寫!

原來我進到第二階段了!

sam0407 iT邦高手 1 級 ‧ 2020-09-03 08:36:53 檢舉

嗯,因為您現在不寫註解,過幾年您就會嚐到自己或別人不寫註解的痛苦,從而發現還是需要寫註解的~~

所謂"欲知前世因,今生受者是;欲知來世果,今生作者是",不寫註解不講前世今生,算是現世報!!

4
japhenchen
iT邦高手 1 級 ‧ 2020-08-31 10:14:47

菜雞+1

一人開發團隊,寫給自己未來嘲笑自己用的......
也可以留下個注腳,哪天發生著作權爭議時,還可以有得查是誰先誰後

多人團隊,我也不想在我離職之後,因後續者無法維護我的程式碼而放棄,重新改寫....

你哪是菜雞!

3
hannahpun
iT邦新手 5 級 ‧ 2020-09-01 22:10:40

我們公司是遵照 JSDOC 寫
https://jsdoc.app/about-getting-started.html
例如

/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {
}

你可以很清楚看到一個 function 輸入什麼回傳什麼 而不是逐一解釋
基本上需要逐一解釋的程式碼一定不是好程式碼 XD

也是有同事討論過寫註解得必要性
基本上假如你完全不用寫註解別人也看得懂你在幹嘛
那堪稱完美
註解必要寫應該就是讓人能快速理解快速使用
所以像一些比較難的共用 function 我甚至會提供一些例子讓別人快速使用

Tim Hsu iT邦新手 5 級 ‧ 2020-09-01 23:08:48 檢舉

我們公司也是用這個方式

yabee5566 iT邦新手 5 級 ‧ 2020-09-02 14:39:05 檢舉

這應該是為了自動文件生成用的吧?
問題像你這範例沒寫註解大家應該也看得懂?
所有的 getBook, getPencil, getPaper
也都要一一寫上//取得書 //取得鉛筆 //取得紙張
感覺就很多餘

之前我是看到類似的註解
其中一條註解叫fw : 分位
分位????
喔 原來是Firmware
話說... 我開發一般都是不看註解的, 除非我看不懂才會去看, 不知道大家是否一樣?

我的注解只寫使用緣由,不寫線上教學,真的不想把接手的人當笨蛋

我要發表回答

立即登入回答