代码中的注释, 需要面向功能注释,而非使用注释

　　写代码注释的时候, 需要倾向写功能,而不是这个是在什么情况下拿来干什么的, 背后的关键问题就是抽象函数需要面对功能抽象,而非使用场景.

　　为什么会有这个问题呢?

　　因为我们一般如果在代码重构的时候, 重构出来的代码一般是由场景和上下文的, 而其原来就是使用场景下的一段代码,抽象成函数以后, 我们会对什么情况下拿来干什么的这个意图更明确, 所以会有些这种注释的清晰.

　　就重构来讲,这是一个思路问题. 一般性的重构,是要抽象出软件中,共性的东西, 抽象成不同的层次和模块. 清晰和优化结构. 

　　

　　下面有一个例子:

　  /// <summary>

        /// 执行插入或修改语句

        /// </summary>

        /// <param name="sqlStr"></param>

        /// <returns></returns>

        public int ExecutNonQuery(string sqlStr)

        {

            return db.ExecuteNonQuery(CommandType.Text, sqlStr);

        }

        注释应该改为: 以NonQuery方式执行Sql,返回影响的行数

 

这个方法是一个很普通的执行sql的方法, 从注释上很明显做了假设,其实这个函数还可以做很多功能,创建索引,约束,建表等等.

 

上面的思路可能有点乱, 那最后总结一下吧:

1：抽象函数和接口应该面向功能,而非使用场景.

2：抽象函数和接口不应该假设使用方的场景.

3：设计函数,应该尽量采用单一功能的思路进行设计,避免设计功能过大的底层函数.