程序注释的原则

写好注释的几条原则：

    1、假设读者的语言水平跟你一样（比如说，不要去解释“什么是字符串，也别去解释什么是赋值语句”）。

 

    2、不要注释那些显而易见的事情。比如下面这条注释是毫无意义的：

                        count=count+1  #add one to count

 

    3、很多程序员会在代码中写上一些以"TODO"或"FIXME"开始的注释，目的是为了提醒他们回来编写或清理一些未解决的问题。

 

    4、如果你在编写某段程序时需要使劲思考的话，那么就应该编写注释，以便别人不会再在这个地方绞尽脑汁。尤其要注意的是，如果你在开发程序或函数时使用要点来进行描述，尽量将这些要点写细一些，在开发工作完成之后，还应该将原来的要点全部保留下来直接当做注释。

 

    5、如果有个bug很难查明，或者其修改方案比较复杂，那么你就应该编写一条注释来对其进行解释。如果不这么做，那么今后其他负责该部分代码的程序员就可能认为它没必要这么复杂并将其改回原来的模样，从而让你的心血付诸东流。

 

    6、如果需要大量注释才能解释清楚某段代码的作用，那么就应该对这些代码进行整理。比如说，如果需要分别对一个函数中的15个列表进行解释，那么就应该将该函数拆分成更小的代码块，每一个分别只处理较少的几个列表。

 

    7、过时的注释还不如没有注释。因此，在修改了某段代码之后，一定要仔细检查相关注释，并对其做出适当的修改以保证其仍能准确描述代码功能。

转载于:https://www.cnblogs.com/blogforTomSminth/p/5495343.html