Python 浅谈注释的重要性

Posted 2020-10-07

       最近参加了一个比赛，然后看到队友编程的代码，我觉得真的是难以下咽，几乎每个字符都要咨询他，用老师的话来说，这就是山炮编程员，所以此时的我意识到写一篇关于注释程序的重要性了，因此特地的写一篇文章帮助大家入门。

      注释不止是为了自己以后看的更清楚，还是为了以后的开发人员所准备的，其实一段时间后，当需要对程序做一些修改或者是改正某个bug的时候，可能未来的我们自己都会忘记相关的细节，所以此时注释显得尤为重要。

      每条注释以井号（#）开始，一直到该行末尾结束，一直到该行末尾结束。我们可以在注释中放任何东西，因为Python 会完全无视他们的存在。为了写好注释，这里给出以后几条规则：

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

     （2） 不要去注释那些毫无意义的事情。比如说：

count = count +1   # add one  to count

      ( 3） 很多程序员会在代码上写上一些以 “ TODO ”  或者  “ FIXME ”开始的注释，目的就是为了提醒他们回来编写或清理一些未完成的一些问题。

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

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

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

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

     （8） 注释不是越多越好，弄得整篇代码都是注释，却很少看到代码，这样就曲解了注释的意思了。

       所以说，一定要养成良好的注释代码的习惯，边写代码边注释，及时的记录下来你的思路，举个例子，代码是鱼，注释就是水，有了正确的注释，鱼才能更好的生存。还有就是多提高自己对代码的解释能力，用精炼的语言表达出代码的核心价值所在，那么你写的代码就是成功的。

    下面举个例子

def find_two_smallest(L):
    ‘‘‘Return a tuple of the indices of the two smallest values in list L‘‘‘
    smallest = min(L)
    min1 = L.index(smallest)
    L.remove(smallest)
    next_smallest = min(L)
    min2 = L.index(next_smallest)
    L.insert(min1,smallest)
    if min1<=min2:
        min2+=1
    return(min1,min2)