注释三原则：what + why + how

这其实可以写成一篇哲学文章，就认识论进行讨论。
举个例子，现在有一个函数，其注释如下：

/*
名称：CalcThread
说明：计算线程
创建人：XX与XX年XX月XX日
*/

这样的注释等于没有注释，因为读者依然不明白这个函数是干什么用的。

人要理解一个东西，需要从内涵和外延两部分出发。
内涵即这个事物本身，这是科学角度去理解。
但是仅仅有内涵是不够的，事物存在的理由是为了人，因此还需要从外延出发进行说明，这是功利主义的角度。

现在这个函数的注释改成如下：

/*
what:计算线程，负责调用相应计算模块进行计算
why:主线程负责接收web端传送的数据并保存在arrData中，这些数据由该计算线程进行真正的计算
how:线程不断进行while循环，一旦发现arrData不为空就开始计算，否则sleep一段时间
*/

读了这样的注释就能理解这个函数了。
重点在于理解，只有懂了内涵和外延才能说理解了。
how则是说明如何使用，在这里不存在使用的问题所以变成了描述机制。对于能反复调用的函数，最好给出一个调用的例子。

如果是一个人写程序，那么创建人和时间就不必了。如果是多个人合作完成，那么最好注明作者和时间。