python文檔 · 零基礎學Python（第一版）

文檔，這個詞語在經常在程序員的嘴里冒出來，有時候他們還經常以文檔有沒有或者全不全為標準來衡量一個軟件項目是否高大上。那么，軟件中的文檔是什么呢？有什么要求呢？python文檔又是什么呢？文檔有什么用呢？文檔很重要。獨孤九劍的劍訣、易筋經的心法、寫著辟邪劍譜的袈裟，這些都是文檔。連那些大牛人都要這些文檔，更何況我們呢？所以，文檔是很重要的。文檔，說白了就是用word（這個最多了）等（注意這里的等，把不常用的工具都等掉了，包括我編輯文本時用的vim工具）文本編寫工具寫成的包含文本內容但不限于文字的文件。有點啰嗦，啰嗦的目的是為了嚴謹，呵呵。最好還是來一個更讓人信服的定義，當然是來自[維基百科](http://zh.wikipedia.org/wiki/%E8%BD%AF%E4%BB%B6%E6%96%87%E6%A1%A3)。 > 軟件文檔或者源代碼文檔是指與軟件系統及其軟件工程過程有關聯的文本實體。文檔的類型包括軟件需求文檔，設計文檔，測試文檔，用戶手冊等。其中的需求文檔，設計文檔和測試文檔一般是在軟件開發過程中由開發者寫就的，而用戶手冊等非過程類文檔是由專門的非技術類寫作人員寫就的。 > > 早期的軟件文檔主要指的是用戶手冊，根據Barker的定義，文檔是用來對軟件系統界面元素的設計、規劃和實現過程的記錄，以此來增強系統的可用性。而Forward則認為軟件文檔是被軟件工程師之間用作溝通交流的一種方式，溝通的信息主要是有關所開發的軟件系統。Parnas則強調文檔的權威性，他認為文檔應該提供對軟件系統的精確描述。 > > 綜上，我們可以將軟件文檔定義為： > > 1.文檔是一種對軟件系統的書面描述； 2.文檔應當精確地描述軟件系統； 3.軟件文檔是軟件工程師之間用作溝通交流的一種方式； 4.文檔的類型有很多種，包括軟件需求文檔，設計文檔，測試文檔，用戶手冊等； 5.文檔的呈現方式有很多種，可以是傳統的書面文字形式或圖表形式，也可是動態的網頁形式那么這里說的Python文檔指的是什么呢？一個方面就是每個學習者要學習python，python的開發者們（他們都是大牛）給我們這些小白提供了什么東西沒有？能夠讓我們給他們這些大牛溝通，理解python中每個函數、指令等的含義和用法呢？有。大牛就是大牛，他們準備了，而且還不止一個。 ## [](https://github.com/qiwsir/ITArticles/blob/master/BasicPython/211.md#查看python文檔)查看python文檔真誠的敬告所有看本教程的諸位，要想獲得編程上的升華，看文檔是必須的。文檔勝過了所有的教程和所有的老師以及所有的大牛。為什么呢？其中原因，都要等待看官看懂了之后，有了體會感悟之后才能明白。 python文檔的網址：[https://docs.python.org/2/](https://docs.python.org/2/)，這是python2.x，從這里也可以找到python3.x的文檔。 [![](https://box.kancloud.cn/2015-07-07_559b39fb22e2c.png)](https://github.com/qiwsir/ITArticles/blob/master/Pictures/21101.png) 除了看網站上的文檔，還有別的方式嗎？有，而且看官并不陌生，此前已經在本教程中多次用到，那就是dir()和help() ~~~ >>> dir(list) ['__add__', '__class__', '__contains__', '__delattr__', '__delitem__', '__delslice__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__getitem__', '__getslice__', '__gt__', '__hash__', '__iadd__', '__imul__', '__init__', '__iter__', '__le__', '__len__', '__lt__', '__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__reversed__', '__rmul__', '__setattr__', '__setitem__', '__setslice__', '__sizeof__', '__str__', '__subclasshook__', 'append', 'count', 'extend', 'index', 'insert', 'pop', 'remove', 'reverse', 'sort'] >>> help(list.__mul__) Help on wrapper_descriptor: __mul__(...) x.__mul__(n) <==> x*n ~~~ 這種查看文檔的方式，在交互模式下經常用到，快捷方便，請看官務必牢記并使用。正如前面已經介紹過的，還有一個文檔：**doc**,help調用的其實就是這個函數里面的內容。 ~~~ >>> print(list.__mul__.__doc__) #與help(list.__mul__)顯示的內容一致 x.__mul__(n) <==> x*n >>> print(list.index.__doc__) #查看index的文檔 L.index(value, [start, [stop]]) -> integer -- return first index of value. Raises ValueError if the value is not present. ~~~ ## 給自己的程序加上文檔在自己編寫程序的時候，也非常希望能夠有類似上面查看python文檔的功能，可以通過某種方式查看自己的程序文檔，這樣顯得自己多牛呀。有一種方法可以實現，就是在你所編寫的程序中用三個雙引號或者單引號成對地出現，中間寫上有關文檔內容。 ~~~ >>> def qiwsir(): ... """I like python""" ... print "http://qiwsir.github.io" ... >>> qiwsir() http://qiwsir.github.io >>> print(qiwsir.__doc__) #用這種方法可以看自己寫的函數中的文檔 I like python >>> help(qiwsir) #其實就是調用__doc__顯示的內容 Help on function qiwsir in module __main__: qiwsir() I like python ~~~ 另外，對于一個文件，可以把有關說明放在文件的前面，不影響該文件代碼運行。例如，有這樣一個擴展名是.py的python文件，其內容是： ~~~ #!/usr/bin/env python #coding:utf-8 import random number = random.randint(1,100) guess = 0 while True: num_input = raw_input("please input one integer that is in 1 to 100:") guess +=1 if not num_input.isdigit(): print "Please input interger." elif int(num_input)<0 and int(num_input)>=100: print "The number should be in 1 to 100." else: if number==int(num_input): print "OK, you are good.It is only %d, then you successed."%guess break elif number>int(num_input): print "your number is more less." elif number<int(num_input): print "your number is bigger." else: print "There is something bad, I will not work" ~~~ 這段程序，就是在[《用while來循環》](https://github.com/qiwsir/ITArticles/blob/master/BasicPython/205.md)中用到的一個猜數字的游戲，它存儲在名為205-2.py的文件中，如果要對這段程序寫一個文檔，就可以這么做。 ~~~ """ This is a game. I am Qiwei. I like python. I am writing python articles in my website. My website is http://qiwsir.github.io You can learn python free in it. """ #!/usr/bin/env python #coding:utf-8 import random number = random.randint(1,100) guess = 0 while True: num_input = raw_input("please input one integer that is in 1 to 100:") guess +=1 if not num_input.isdigit(): print "Please input interger." elif int(num_input)<0 and int(num_input)>=100: print "The number should be in 1 to 100." else: if number==int(num_input): print "OK, you are good.It is only %d, then you successed."%guess break elif number>int(num_input): print "your number is more less." elif number<int(num_input): print "your number is bigger." else: print "There is something bad, I will not work" ~~~ 最后，推薦一篇相當相當好的文章，與列位分享： [Python 自省指南:如何監視您的 Python 對象](http://www.ibm.com/developerworks/cn/linux/l-pyint/#ibm-pcon)