ffective Python 讀書筆記: 第49條: 爲每個函數、類和模塊編寫文檔字符串

# -*- encoding: utf-8 -*-

import os

'''
第49條: 爲每個函數、類和模塊編寫文檔字符串

關鍵:
1 docstring
含義: def語句之後，可以提供docstring，將卡法文檔與函數關聯
形式: """Return""", 注意 """之後接的單詞之間沒有空格 
用法: result = repr(palindrome.__doc__)
函數的__doc__即會返回最終的函數的文檔字符串

2 Sphinx
文檔生成工具。可以將純文本轉換爲HTML格式

3 爲模塊編寫文檔
模塊有頂級的docstring.作爲源文件的第一條語句。
用三重雙引號把它括起來。
docstring的第一行: 描述模塊的用途，下面的內容則包含細節。
頂行下面空一行，寫詳細內容。頂行和三重引號之間沒有空格
用法:
"""My First Module.

It is used to tell you how to
write docstring of module.

"""

4 爲類編寫文檔
頭一行表示類的作用，空一行，後面的內容表示細節

class Student(object):
    """It means student class.
    
    It includes insert/delete/edit/retrieve
    methods.
    
    """

5 爲函數編寫文檔
第一行表示函數功能，空一行，後面內容表示細節。
樣例:
def process(data):
    """It is used to rocess data.
    
    The stepes of processing data are as below:
    Firstly, filter invalid data.
    """
    
6 總結
用docstring爲模塊，類，方法寫文檔字符串，
三重引號後無空格，接第一行表示用途，
然後空一行，後面內容表示細節。

參考:
Effectiv Python 編寫高質量Python代碼的59個有效方法
'''

def palindrome(word):
    """Return True if the given word is a palindrome"""
    return word == word[::-1]


def process():
    result = repr(palindrome.__doc__)
    print result
    print type(result)


if __name__ == "__main__":
    process()