摘要：軟件文檔或者源代碼文檔是指與軟件系統(tǒng)及其軟件工程過程有關(guān)聯(lián)的文本實體。而則認為軟件文檔是被軟件工程師之間用作溝通交流的一種方式，溝通的信息主要是有關(guān)所開發(fā)的軟件系統(tǒng)。則強調(diào)文檔的權(quán)威性，他認為文檔應(yīng)該提供對軟件系統(tǒng)的精確描述。

文檔，這個詞語在經(jīng)常在程序員的嘴里冒出來，有時候他們還經(jīng)常以文檔有沒有或者全不全為標準來衡量一個軟件項目是否高大上。那么，軟件中的文檔是什么呢？有什么要求呢？python文檔又是什么呢？文檔有什么用呢？

文檔很重要。獨孤九劍的劍訣、易筋經(jīng)的心法、寫著辟邪劍譜的袈裟，這些都是文檔。連那些大牛人都要這些文檔，更何況我們呢？所以，文檔是很重要的。

文檔，說白了就是用word（這個最多了）等（注意這里的等，把不常用的工具都等掉了，包括我編輯文本時用的vim工具）文本編寫工具寫成的包含文本內(nèi)容但不限于文字的文件。有點啰嗦，啰嗦的目的是為了嚴謹，呵呵。最好還是來一個更讓人信服的定義，當然是來自維基百科。

  
軟件文檔或者源代碼文檔是指與軟件系統(tǒng)及其軟件工程過程有關(guān)聯(lián)的文本實體。文檔的類型包括軟件需求文檔，設(shè)計文檔，測試文檔，用戶手冊等。其中的需求文檔，設(shè)計文檔和測試文檔一般是在軟件開發(fā)過程中由開發(fā)者寫就的，而用戶手冊等非過程類文檔是由專門的非技術(shù)類寫作人員寫就的。

  
早期的軟件文檔主要指的是用戶手冊，根據(jù)Barker的定義，文檔是用來對軟件系統(tǒng)界面元素的設(shè)計、規(guī)劃和實現(xiàn)過程的記錄，以此來增強系統(tǒng)的可用性。而Forward則認為軟件文檔是被軟件工程師之間用作溝通交流的一種方式，溝通的信息主要是有關(guān)所開發(fā)的軟件系統(tǒng)。Parnas則強調(diào)文檔的權(quán)威性，他認為文檔應(yīng)該提供對軟件系統(tǒng)的精確描述。

  
綜上，我們可以將軟件文檔定義為：

  
1.文檔是一種對軟件系統(tǒng)的書面描述；

  2.文檔應(yīng)當精確地描述軟件系統(tǒng)；

  3.軟件文檔是軟件工程師之間用作溝通交流的一種方式；

  4.文檔的類型有很多種，包括軟件需求文檔，設(shè)計文檔，測試文檔，用戶手冊等；

  5.文檔的呈現(xiàn)方式有很多種，可以是傳統(tǒng)的書面文字形式或圖表形式，也可是動態(tài)的網(wǎng)頁形式

那么這里說的Python文檔指的是什么呢？一個方面就是每個學(xué)習(xí)者要學(xué)習(xí)python，python的開發(fā)者們（他們都是大牛）給我們這些小白提供了什么東西沒有？能夠讓我們給他們這些大牛溝通，理解python中每個函數(shù)、指令等的含義和用法呢？

有。大牛就是大牛，他們準備了，而且還不止一個。

真誠的敬告所有看本教程的諸位，要想獲得編程上的升華，看文檔是必須的。文檔勝過了所有的教程和所有的老師以及所有的大牛。為什么呢？其中原因，都要等待看官看懂了之后，有了體會感悟之后才能明白。

python文檔的網(wǎng)址：https://docs.python.org/2/，這是python2.x，從這里也可以找到python3.x的文檔。

除了看網(wǎng)站上的文檔，還有別的方式嗎？

有，而且看官并不陌生，此前已經(jīng)在本教程中多次用到，那就是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

這種查看文檔的方式，在交互模式下經(jīng)常用到，快捷方便，請看官務(wù)必牢記并使用。

正如前面已經(jīng)介紹過的，還有一個文檔：doc,help調(diào)用的其實就是這個函數(shù)里面的內(nèi)容。

>>> print(list.__mul__.__doc__)     #與help(list.__mul__)顯示的內(nèi)容一致
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文檔的功能，可以通過某種方式查看自己的程序文檔，這樣顯得自己多牛呀。

有一種方法可以實現(xiàn)，就是在你所編寫的程序中用三個雙引號或者單引號成對地出現(xiàn)，中間寫上有關(guān)文檔內(nèi)容。

>>> def qiwsir():
...     """I like python"""
...     print "http://qiwsir.github.io"
... 
>>> qiwsir()
http://qiwsir.github.io

>>> print(qiwsir.__doc__)   #用這種方法可以看自己寫的函數(shù)中的文檔
I like python

>>> help(qiwsir)            #其實就是調(diào)用__doc__顯示的內(nèi)容

Help on function qiwsir in module __main__:

qiwsir()
    I like python

另外，對于一個文件，可以把有關(guān)說明放在文件的前面，不影響該文件代碼運行。

例如，有這樣一個擴展名是.py的python文件，其內(nèi)容是：

#!/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

這段程序，就是在《用while來循環(huán)》中用到的一個猜數(shù)字的游戲，它存儲在名為205-2.py的文件中，如果要對這段程序?qū)懸粋€文檔，就可以這么做。

"""
   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

最后，推薦一片相當相當好的文章，與列位分享：

Python 自省指南:如何監(jiān)視您的 Python 對象