代碼注釋規范

• 
  
  • 注釋形式統一
    • 在整個解決方案中，使用一致的標點和結構的樣式來構造注釋，是架起團隊成員溝通的橋梁既可以提高程序開發效率，也可以保證程序的可維護性。但是請不要試圖使用這個標准來破壞舊解決方案的注釋規范。一個解決方案的規范標准一致性才是最重要的。     
  • 命名規范
    • 解決方案：名稱采用駝峰命名法（lowerCamelCase 風格）。
    • 類庫、項目：名稱首字母大寫（UpperCamelCase 風格）     
    • 控制器、類名：首字母大寫（UpperCamelCase 風格），遵循駝峰形式，如果多個單次組成的，每個單次首字母大寫。
      • public class Class{}
    • 變量名：成員變量、局部變量 首字母小寫（lowerCamelCase 風格）。
    • 方法名：首字母大寫（UpperCamelCase 風格）。
    • 參數名：首字母小寫（lowerCamelCase 風格）。
    • 抽象類名：使用Abstract開頭。
    • 異常類名使用：Exception 結尾。
    • 異步方法使用：Async結尾。
    • 命名空間和模型名稱相同時候：命名空間使用復數形式。     
  • 注釋規范
    • 好的注釋規范是一個程序員的基本修煉，好的注釋規范更能體現一個程序員的邏輯思維。   
    • 控制器注釋（Controller）
      • 主要包含：控制器用途，ApiVersion，路由，創建者，創建版本，支持版本，創建日期，代碼缺陷（可選），注意事項（可選）等。 
      • /// <summary>
        /// description:獲取用戶信息 
        /// author：譚洪軍
        /// varsion:1.0
        /// date:2019-12-12 
        /// </summary>
        /// <returns>AppUser</returns>
        [Route("Get")]
        [HttpGet, MapToApiVersion("1.0")]
        [ApiVersion("1.1")]
        [ProducesResponseType(typeof(AppUser), StatusCodes.Status200OK)]
        [ProducesResponseType(StatusCodes.Status404NotFound)]
        [ProducesDefaultResponseType]
        public async Task<IActionResult> GetAsync()
        {
        }
           
    • 類注釋（Class）
      • 主要包含：類的用途、創建者、創建版本、創建日期、代碼缺陷（可選）、注意事項（可選）等。
      • /// <summary>
        /// description：用戶服務數據上下文
        /// author：譚洪軍
        /// varsion:1.0
        /// date:2019-12-12 12：02
        /// warning:字段的標記主鍵，范圍驗證等將由flutend轉移到類里面有attribute實現。
        /// </summary>
        public class UserContext : DbContext
        {

         

        }
         
    • 構造方法注釋（Construction method）
      • 主要包含：聲明該類的構造函數、入參等信息。
      • /// <summary>
        /// 上下文構造方法
        /// </summary>
        /// <param name="options">DbContextOptions</param>
        public UserContext(DbContextOptions<UserContext> options) : base(options)
        {

         

        }
             
    • 方法注釋(Methods)
      • 主要包含：方法的用途、入參、返回值、異常信息、創建者、創建版本、創建日期、代碼缺陷（可選）、注意事項（可選）等。  
      • /// <summary>
        /// description:更新/定義代碼中的數據模型 
        /// author：譚洪軍
        /// varsion:1.0
        /// date:2019-12-12 
        /// throws:
        /// </summary>
        /// <param name="modelBuilder">ModelBuilder</param>
        protected override void OnModelCreating(ModelBuilder modelBuilder)
        {
        }
          
    • 代碼塊注釋（Block）
      • 主要包含：代碼塊的用途
      • #region 定義數據模型的表名，字段，主鍵等

         

        modelBuilder.Entity<AppUser>()
        .ToTable("Users")
        .HasKey(u => u.Id);

         

        #endregion
           
    • 單句注釋
      • 主要包含：代碼的用途
      • //定義AppUser數據模型的數據庫表為Users，且主鍵為Id
        modelBuilder.Entity<AppUser>()
        .ToTable("Users")
        .HasKey(u => u.Id);   
    • 字段注釋 
      • 主要包含：字段的用途
      • /// <summary>
        /// 用戶表數據集
        /// </summary>
        public DbSet<AppUser> Users { get; set; }