本站電子書

您可以在這些電子書店找到本站電子書: Google Play 圖書iBooks StoreHyReadReadmooPubu
===>>>本站推出學習遊戲意見調查<<<===《如何自學程式設計》入選 Google Play 台灣地區2016年度最佳書籍

Python 入門指南 V2.00 - 單元 13 - 文件字串




文件字串 (documentation string) 定義在模組 (module) 、函數 (function) 、類別 (class) 及方法 (method) 中,用為程式的說明文件,可用預設屬性 (attribute) __doc__ 存取



說明文件不外是解釋程式某部分的使用方式,通常會舉出簡單的例子,傳統程式語言 (programming language) 的說明文件大都是額外編寫,印成紙書或放在網路供人查詢,或是以註解 (comment) 形式加進原始程式碼 (source code) 中, Python 文件字串的特點讓程式設計師可以邊寫程式邊查文件,無須翻紙書或查網路。


我們先進入 Python 的互動式介面來看看吧!下面印出內建函數 int() 的屬性 __doc__



int() 用來建立整數物件 (object) ,因此回傳一個整數物件,這裡可以看到 int() 的解釋與用法。


下面再來看看串列 (list) 的文件字串



串列的文件字串只有簡單印出用法,大體上文件字串是依需要來設置。文件字串分成兩種,一種是單行的文件字串,另一種則是多行,下面我們用單元 8big() 函數示範單行文件字串的寫法


   def big(a, b):
      """Return the bigger argument."""
      if a > b:
         return a
      else:
         return b

文件字串採用三個引號,也就是字串前後都用三個引號圍起來,單行的文件字串就是簡單的寫明函數用途


   """Return the bigger argument."""

多行的文件字串同樣用三引號字串 (triple-quoted string) ,如下例


   def big(a, b):
      """Return the bigger argument.
   
         Args: 
            a - the first one.
            b - the second one.
      """
      if a > b:
         return a
      else:
         return b

第一行同樣是函數用途,之後空一行,下面才是進一步的解釋說明,此例解釋參數 (parameter) 的用途。有沒有發現三引號字串是可以跨行的呢?是的,三引號字串可以跨行,因為三引號字串的主要用途就是當作文件字串,文件字串通常是多行的敘述。


下面我們替 class_dmeo9.py 加進模組、類別與方法的文件字串


001"""An example of the Demo class.
002
003   It demonstrates the docstring. 
004"""
005
006# This is a comment of a class.
007class Demo:
008   """A docsting of the class."""
009   # This is a comment of the method.
010   def __init__(self, v1=11, v2=22):
011      """A docsting of the __init__."""
012      self.__a = v1
013      self.__b = v2
014   
015   # This is a comment of a method.
016   def do_something(self):
017      """A docsting of a method."""
018      return self.__a + self.__b
019
020if __name__ == "__main__":
021   d = Demo(12, 34)
022   print(d.do_something())
023 
024# 檔名: class_demo10.py 
025# 作者: Kaiching Chang 
026# 時間: July, 2014

這裡僅作示範用,因此文件字串中都採取簡單的文字。

我們可以看到模組的文件字串出現在檔案的最開始,類別、方法或函數的文件字串都在關鍵字 (keyword) 的下一行,至於註解則在關鍵字的上一行,除了文件字串的位置須固定外,註解的位置是 Python 社群的習慣寫法,如果要對整個類別、方法或函數做註解,通常都會寫在關鍵字的上一行。


由於文件字串是用途及簡單例子,所以註解內容不應該與文件字串相同或相似,基本上註解的目的主要是對程式碼額外說明,至於說明內容依需要而定。


倒是不管文件字串或是註解都應按照開發團隊的習慣來走,我們這裡介紹的是官網 PEP 8PEP 257 所建議的寫法。

接下來我們開發軟體的方式,帶領讀者開發 GUI 的編密碼軟體,藉此介紹更多的 Python 特性囉!


中英文術語對照


文件字串documentation string
模組module
函數function
類別class
方法method
屬性attribute
程式語言programming language
註解comment
原始程式碼source code
物件object
串列list
三引號字串triple-quoted string
參數parameter
關鍵字keyword

重點整理


  1. 文件字串用以說明模組、函數、類別及方法的功能,可用預設屬性 __doc__ 存取。
  2. 定義文件字串採用可以跨行的三引號字串,放在模組的開頭或 classdef 的下方第一行。


問題與討論


  1. 文件字串是什麼?為什麼要在程式中設置文件字串?
  2. 什麼是三引號字串?這跟字串有什麼不同?

練習


  1. 寫一個程式 exercise1301.py ,替 exercise1201.py 加入文件字串。
  2. 寫一個程式 exercise1302.py ,替 exercise1202.py 加入文件字串。
  3. 寫一個程式 exercise1303.py ,替 exercise1203.py 加入文件字串。

the end

沒有留言: