代码注释规范

Posted tsir

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了代码注释规范相关的知识,希望对你有一定的参考价值。


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

以上是关于代码注释规范的主要内容,如果未能解决你的问题,请参考以下文章

3.7 代码注释和编码规范

代码注释规范

php注释规范

java代码注释规范

php 注释 规范

「Python编程规范」为Python代码添加注释