Clean Code 筆記 之 第四章 如何應用註釋

繼上一篇筆記以後，今天咱們討論一下 代碼中是存在註釋是不是一件好的事情。

 

在咱們開發的過程當中講究「名副其實，見名識意」，這也每每是不少公司的要求，可是有了這些要求是否是咱們的代碼中若是存在註釋是否是意味着咱們的 函數，變量，以及類 的命名就不符合了「名副其實，見名識意」。

咱們先區分一下注釋的類別，註釋通常分爲如下幾種：

• 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;

          }

View Code

2， 多行註釋：

以「/*」開頭 「*/」 結尾 經常使用於描述說明一段代碼以及類註釋或者說代碼塊經常使用於文件的頂部。說明做者信息，時間若是是開源的這包含開源的更多說明。
一般使用以下:

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

View Code

3， 文檔註釋：

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

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

View Code

如下是官方建議的文檔標記 點擊標籤會制動跳轉

 

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()))

  這兩個你更喜歡哪一個

View Code

好的註釋的特徵：

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.

View Code

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 =>
{});

}

View Code

3：對意圖的解釋

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

5： TODO註釋： 主要描述應該作的目前尚未作的事情。

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

應避免的註釋

應該避免如下幾點：

1： 誤導性註釋

2： 日誌式註釋

3： 廢話註釋

4： 標記位置的註釋

5： 括號後的註釋

6： 歸屬與簽名

7： 註釋掉的代碼

8： Html 註釋

以上沒有一一舉例的緣由是個人PPT是一份演示的PPT，裏面不少公司的代碼不便貼出，抱歉。

不足之處還請指出