代码注释规范

Posted 2020-11-25 tsir

• 
  
  • 注释形式统一
    • 在整个解决方案中，使用一致的标点和结构的样式来构造注释，是架起团队成员沟通的桥梁既可以提高程序开发效率，也可以保证程序的可维护性。但是请不要试图使用这个标准来破坏旧解决方案的注释规范。一个解决方案的规范标准一致性才是最重要的。     
  • 命名规范
    • 解决方案：名称采用驼峰命名法（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; }