iT邦幫忙

2018 iT 邦幫忙鐵人賽
DAY 5
1
Software Development

保持前進、持續優化程式碼內涵系列 第 5

05. 隱藏在原始碼的小幫手~註解

如果有幸接手他人的程式碼,有可能會發生以下幾種情況,

  • 基本上不存在 IDE 自行產生的註解以外的註解。
  • 滿滿的註解起來的程式碼,但是這些註解,都是不知道還有沒有用途
  • 完全不明白意思的註解

沒有註解的程式碼

假若該程式碼,具有高閱讀性,沒有註解,其實沒有那麼重要。但是,如果程式內容本身不易閱讀,為了未來的自己,或是接收程式的後人,請養成註解的習慣。

無用的註解

public int StatisticCostAmount(...)
{
    ...
    // 解法二
    foreach(var item in items)
    {
        ...
       
           
        // 2017/5/12 修改
        ...        
    }
    // Console.WriteLine($"total={total}")
}

開發的過程中,有時候,為了 DEBUG,可能會在程式碼中,插入除入用的程式碼。像上面範例中出現的 Console.WriteLine(...),基本上,在完成除錯後,應該要刪除這些有特定用途的程式碼。

食之無味、棄之可惜的註解

public int StatisticCostAmount(...)
{
    ...
    // 做法一
    // .....
    // .....
    
    // 做法二
    foreach(var item in items)
    {
        ...        
    }
}

這種情況可能發生在接收過來的程式碼,或是為了效能改寫原本正常運行的的程式寫法。改寫完成後,想保留本來的寫法,以便以後可以回來查詢的機會。

事實上,如果修改後的程式沒有發生任何問題,回來查看被註解掉的程式碼機會,基本上無限趨近於 0。
實務上,在修改前,應該就要將原本的程式碼上傳至版控軟體中,進行任何的功能變動時,應養成上版控的習慣。

保留註解程式碼的原因,是為了回朔當初的寫法或功能,請愛用版控軟體,保持程式碼的清潔,以提升閱讀性。

若是一定要保留在程式碼中,應該針對註解的部份,額外增加註解,說明保該程式碼保留下來的原因。

無法解讀的註解

public int StatisticCostAmount(...)
{
    ...    
    foreach(var item in items)
    {
        ...
        
        // 2017/5/12 修改
        ...        
    }
}

看到這句註解,應該是滿頭霧水,註解的用意是?

  • 單純表示 2017/5/12 修改的?
    如果只是單純註明這段程式碼修改的日期,那這個註解本身是沒有任何意義的,應該盡可能避免。小弟看到這種註解,通常都是刪除。

  • 告知協同開發的伙伴說明程式碼己經修改?
    一般而言,如果需要協同開發程式,表示軟體有一定的規模。請愛用版本控制軟體,版控軟體可以更有效的比對出異動的程式碼。
    如果工作環境還沒有版控軟體,麻煩試著自行架設,會發現新的世界。

  • 修改程式碼是因為需求變動?
    如果是因為臨時性的需求變動,特別標註修改日期,那麼應該連帶說明修改的原因。以確保其他人看到這段程式碼時,第一時間可以明白修改的原因。

有益的註解

有些時候,可能某個功能的實作是因為特定因素,所以採用特定的做法,這時,就可以特別註明,讓後面的人知道,避免在維護程式時,將功能改壞。

回顧

軟體開發過程中,為了修改程式邏輯,經常會出現將原本的程式碼區段註解,避免之後還有派上用場旳時間。但是在完成開發後,整理程式碼時,應該清除將這些暫時註解掉的程式碼。

若程式碼己經具有高閱讀性,某方面而言,是可以替代一定程度的註解。但是註解可沒有那麼單純。註解中,有時候,會特別記錄重要的資訊,而這些資訊,正好是程式碼本身無法表示出來的。

Clean Code 一書中,關於註解的章節中,提到好的程式碼,應該程式碼本身就是最好的註解,雖然無法避免使用註解進行說明,但應該該竭盡所能,讓註解減少到最低。對於這個說法,很多人抱持的不同看法,算是滿有爭議的說法。但也很值得我們去思考的這個問題。

推薦

書藉

  1. Robert C. Martin, Clean Code 無瑕的程式碼

相關文章推薦


上一篇
04. 攻城獅最討厭的、但又必需作的事情~命名規則
下一篇
06. 避不開的基本功。持續優化程式碼的根本—重構 (待補完)
系列文
保持前進、持續優化程式碼內涵30

1 則留言

0
Kuma
iT邦新手 5 級 ‧ 2017-12-10 21:48:47

推作者。作者是否也發現,看完本書,coding變成一件超麻煩的事 XD

伊恩 iT邦新手 5 級‧ 2017-12-10 21:51:21 檢舉

這到是真的,但這偏偏又是多人協作時,避不開的事啊

我要留言

立即登入留言