如何提高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 等等.善于利用能制作出非常
漂亮的文档