學寫程式時都會學到如何使用註解，雖然每個語言註解的方式不盡相同，但是幾乎所有語言都會有註解代碼的功能。當我們不需要某一段代碼時、當我們想要解釋代碼時、當需要標示未完成的工作時...等，我們都會在代碼中使用註解。今天我們就來聊聊什麼時候適合使用註解，而什麼時候不適合使用註解。

不適合的情境

1. 註解暫時不要的代碼

   • 很多時候我們寫了一些代碼，忽然因為臨時的需求變更，導致暫時不需要這些代碼了，所以我們就註解掉這些代碼，心中期待著有一天需求回來需要加回來的時候，可以快速的反註解並啟用。但是大多時候都是這些代碼就一輩子不會用了或者是需求有些改變而導致這些代碼直接啟用。

     ⇒ 但是其實這並不必要，因為現代在大部分的協作場合都已經習慣使用版本控制了，所以我們應該直接刪除這些代碼，讓版本控制去記得這些代碼，而不是透過註解來保留這些暫時不用的代碼。

2. 解釋代碼的行為

   • 以下面這段代碼為例，他在每一段代碼區塊上面描述了這段代碼的工作內容。

   public string Encrypt(string plainText)
   {
       // Create a memory stream.
       MemoryStream ms = new MemoryStream();
   
       // Create a CryptoStream using the memory stream and the 
       // CSP DES key.
       ICryptoTransform encyptor = _EncryptoProvider.CreateEncryptor(_DesKey, _Desiv);
       CryptoStream encStream = new CryptoStream(ms, encyptor, CryptoStreamMode.Write);
   
       // Create a StreamWriter to write a string
       // to the stream.
       StreamWriter sw = new StreamWriter(encStream);
   
       // Write the plaintext to the stream.
       sw.WriteLine(plainText);
   
       // Close the StreamWriter and CryptoStream.
       sw.Close();
       encStream.Close();
   
       // Get an array of bytes that represents
       // the memory stream.
       byte[] buffer = ms.ToArray();
   
       // Close the memory stream.
       ms.Close();
   
       // convert the encrypted byte array to string and return it.
       return Convert.ToBase64String(buffer);
   }
   

   大部分框架所提供的類別和方法已經具備基本的Clean Code，所以不需要特別為其解釋行為。

   更多的使用者應該整理代碼，利用抽取方法整理代碼，讓方法名稱與方法簽章解釋行為。

   有些時候從網路上找到的解法也會有這種情況，但是那是提供解法的人為了解釋他的解法而加上去的。

適合的場合

1. 用註解解釋複雜的最佳化過的演算法邏輯

   • 我們會在效能瓶頸的部分做優化，例如在做圖片運算時，對於每次迴圈或記憶體都需要計較的時候，我們會用一些比較不易理解寫法來寫代碼。在這種狀況下，就會比較適合使用一些註解來輔助理解代碼，為將來修改時減少一些閱讀成本。

2. 有些API 文件產生工具會需要在方法名稱上加上一些固定格式的註解

   /**
    * Returns HTML for a foo.
    *
    * @param array $variables
    *   An associative array containing:
    *   - foo: The foo object that is being formatted.
    *   - show_bar: TRUE to show the bar component, FALSE to omit it.
    *
    * @ingroup themeable
    */
   function theme_foo($variables) {
   

大多數的情況善用方法名稱與方法簽章都有效取代註解，習慣讓代碼本身就具備呈現意圖的能力，讓代碼具備可讀性就能大大的減少註解的使用，讓代碼維持乾淨的狀態。