繼上一篇筆記之後，今天我們討論一下 程式碼中是存在註釋是否是一件好的事情。

在我們開發的過程中講究“名副其實，見名識意”，這也往往是很多公司的要求，但是有了這些要求是不是我們的程式碼中如果存在註釋是不是意味著我們的 函式，變數，以及類 的命名就不符合了“名副其實，見名識意”。

我們先區分一下注釋的類別，註釋一般分為以下幾種：

• 1， 單行註釋
• 2， 多行註釋
• 3， 文件註釋
• 4， #region 摺疊註釋，可以將 程式碼摺疊

 註釋的類別

1， 單行註釋：

在以 “//” 開頭，用以說明一行程式碼的作用放置位置 看習慣或者公司要求合理就行。常用於函式內部，在很多的開原始碼中檔案的頭部我同樣見到很多人使用單行註釋進行說明，靈活就好。
體現形式如下：

 public List<string> getVipUserNameByUserType()
          {
            // Vip user name list
            var vipUserNames = new List<string>();

            foreach (var user in Users)
            {

                if (user.Type = "VIP")

                    vipUserNames.Add(user.Name);
            }
            return vipUserNames;

          }

2， 多行註釋：

以“/*”開頭 “*/” 結尾 常用於描述說明一段程式碼以及類註釋或者說程式碼塊常用於檔案的頂部。說明作者資訊，時間如果是開源的這包含開源的更多說明。
通常使用如下:

/*
    * 作者：〈版權〉
    * 描述：〈描述〉
    * 建立時間：YYYY-MM-DD
    * 作用：
*/

3， 文件註釋：

也就是常用的XML 註釋：它的說明性更加的強烈，多用於類以及函式上，當然屬性上同樣可以使用：
如下所示：

        /// <summary>
        /// MyClass
        /// </summary>
        public class MyClass
        {
            /// <summary>
            /// MyProperty
            /// </summary>
            public int MyProperty { get; set; }
            /// <summary>
            /// MyMethod
            /// </summary>
            public void MyMethod(){  }
        }

以下是官方建議的文件標記 點選標籤會制動跳轉

4， #region ： 摺疊註釋，常用於描述多個函式的基本作用

書中最喜歡的話

好的註釋不能美化糟糕的程式碼，真正好的註釋是你想盡辦法不去謝的註釋。懷註釋都是糟糕程式碼的支撐或藉口，或者是對錯誤決策的修正。

下面看一個例子

       //Check to see if the employee is eligible for full benefits
（1）If((employee.flags & HOURLY_FLAG)&& (employee.age>65))

（2）If(employee.isEligibleForFullBenefits()))

  這兩個你更喜歡哪個

好的註釋的特徵：

1：表示法律資訊（這樣的註釋一般出現在文件頂部說明作用以及協議）

// Copyright (c) .NET Foundation. All rights reserved
// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.

2：提供資訊的註釋（指無法通過命名提供資訊如要 註釋輔助的）

public void ConfigureServices(IServiceCollection services)
{

// These two middleware are registered via an IStartupFilter in UseIISIntegration but you can configure them here.

services.Configure<IISOptions>(options =>
{});

}

3：對意圖的解釋

4： 警示：告知其他人會出現某種後果的註釋

5： TODO註釋： 主要描述應該做的目前還沒有做的事情。

6： 放大：提示不合理之物的重要性。

應避免的註釋

應該避免以下幾點：

1： 誤導性註釋

2： 日誌式註釋

3： 廢話註釋

4： 標記位置的註釋

5： 括號後的註釋

6： 歸屬與簽名

7： 註釋掉的程式碼

8： Html 註釋

以上沒有一一舉例的原因是我的PPT是一份演示的PPT，裡面很多公司的程式碼不便貼出，抱歉。

不足之處還請指出

&n