写代码注释的时候, 需要倾向写功能,而不是这个是在什么情况下拿来干什么的, 背后的关键问题就是抽象函数需要面对功能抽象,而非使用场景.
为什么会有这个问题呢?
因为我们一般如果在代码重构的时候, 重构出来的代码一般是由场景和上下文的, 而其原来就是使用场景下的一段代码,抽象成函数以后, 我们会对什么情况下拿来干什么的这个意图更明确, 所以会有些这种注释的清晰.
就重构来讲,这是一个思路问题. 一般性的重构,是要抽象出软件中,共性的东西, 抽象成不同的层次和模块. 清晰和优化结构.
下面有一个例子:
/// <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：设计函数,应该尽量采用单一功能的思路进行设计,避免设计功能过大的底层函数.