2、程序注释

概述

• 注释应简单清晰，易于理解代码表达的逻辑关系和功能
• 代码中应尽量减少不必要的注释，过多的注释反而会引起迷惑
• 注释应准确，不应有多义性

类注释

• 在命名空间之上，Using引用之下
• 主要描述创建类的作者、日期、功能描述和版本

    /// <summary>
    /// ClassName: FactoryHis_Hangzhou
    /// Description: His业务工厂类
    /// @Author xxx
    /// @Create 2024/03/17 18:17
    /// @Version 1.0
    /// </summary>
    [Description("杭州")]
    public class FactoryHis_Hangzhou : IFactoryHis
    {
    }

文档注释

• 在类之上，命名空间之下

/// <summary>
/// 用户相关业务逻辑处理
/// </summary>
public class UserBusiness : BaseBusiness<Db_User>, IUserBusiness, ITransientDependency
{
}

• 在属性字段定义

/// <summary>
/// 部门名称
/// </summary>
public string DepartmentName { get; set; }

• 在方法描述上，应填入具体参数含义

/// <summary>
/// 通过用户id查询用户信息
/// </summary>
/// <param name="id">用户id</param>
/// <returns>用户信息</returns>
public async Task<AjaxResult> GetTheOneAsync(string id)
{
}

单行注释

• 单行注释都在语句块之上，不再一行语句之后进行注释，注释只标记一段语句块操作是做什么用的，至于单个语句的意思无需注释。

正例

 //解析外部入参
 var eReq = biz.J2Entity<ExternalReqProjects>();

 //封装内部请求参数
 var iReq = new InternalReqProjects
 {
     SecretKey = "2342342"
 };

反例

 var eReq = biz.J2Entity<ExternalReqProjects>(); //解析外部入参

 var iReq = new InternalReqProjects //封装内部请求参数
 {
     SecretKey = "2342342"
 };