如何提高python程序的可维护性？

如何提高程序的可维护性？

在接手别人代码的时候。我们常常抱怨前任代码写的太差。导致维护行非常长.最后发现花在维护上的时间
多得足够自己重新写一个。有些人于是抱着奋起一击鱼死网破的态度，推倒重写.结果是浪费了一大票时间。而且
写完之后发现。自己写的代码可维护性往往不见的比前任好多少.

怎样才能提高程序的可维护性呢？ 写文档应该是最容易想到的选择了,完备的文档能让人更易理解程序.

但编写文档有缺点:
1，文档和代码不同步.当代码做出变更时，文档却没有做出类似的变更。
2，开发时文档的重要性偏低。往往为了赶时间而放弃写文档

所以我们需要从python中找到一些办法，能够提供高质量的文档。同时又不至于带来过大的负担

我找到的第一个办法是doctest模块

看一段代码，知道它怎么使用。是干什么用的。最简单快捷的办法是看例子。有了例子。再想去用就是
照葫芦画瓢了. 所以如果在文档里写上例子.对理解代码会有很大的帮助。
这些例子用法就是doctest可以提供的

doctest干什么？
doctest 模块让您可以在文档字符串（docstrings）内嵌入注释以显示各种语句的期望行为，尤其是
函数和方法的结果。这样做很像是让文档字符串看起来如同一个交互式 shell 会话。

     def big(i,j):
     '''
     doctest:
     >>> big(12,13)
     13
     ''' 
         return i if i > j else j

     if __name__ == '__main__':
         import doctest
         doctest.testmod()

     $python test.py -v

     Trying:
    	big(12,13)
     Expecting:
    	13
     ok
     1 items had no tests:
     __main__
     1 items passed all tests:
     1 tests in __main__.big
     1 tests in 2 items.
     1 passed and 0 failed.
     Test passed.

在函数下面定义了注释.使用交互式提示符 >>>。在后面写上python语句.就好像是从交互式shell里
拷贝粘贴的一样.然后在下面写出预期的输出. 比如调用big(12,13) 函数返回13。然后通过命令行调用。
就能完成一次单元测试。

对类的测试也差不多.测试代码如下

     #coding:utf-8
     class Bird:
     """
     doctest:
     >>> bird = Bird('kula')
     >>> bird.song()
     'kula'
     """

         def __init__(self,name):
             self.name = name

         def song(self):
             return self.name

     if __name__ == '__main__':
         import doctest
         doctest.testmod()

     $python test.py -v

     Trying:
     	 bird = Bird('kula')
     Expecting nothing
     ok
     Trying:
         bird.song()
     Expecting:
         'kula'
     ok
     3 items had no tests:
         __main__
         __main__.Bird.__init__
         __main__.Bird.song
     1 items passed all tests:
         2 tests in __main__.Bird
     2 tests in 4 items.
     2 passed and 0 failed.
     Test passed.

由此完成了对这个类的单元测试.同时注释里留下的单元测试教会了我们怎么使用这个类和函数.一举多得！

文档在代码里.每次查阅还要翻代码.也不方便.怎么办？
java里 有一个javadoc模块.可以自动从注释生成文档. python也有类似的模块.有一个模块叫epydoc。
能够根据注释生成非常详尽的文档.
只需要
$epydoc --html test.py
就能在目录下生成一份精美的html文档！

同时,epydoc有很多有用的标签.如 @type @rtype @param @return 等等.善于利用能制作出非常
漂亮的文档