如何編寫高質量的程式呢？ 在《Web服務端軟體的的服務品質概要》闡述了程式的常見質量屬性及實現策略方法，本文將通過一個 Python 實現的圖片檔案批量重新命名工具來演示如何逐步提升程式質量。
圖片檔案批量重新命名工具實現的功能是：將指定目錄 /home/user/path/to/photos/(xxx.png,yyy.png) 下的圖片批量重新命名為 prefix0001.png, prefix0002.png, …
雛形
首先，可以編寫出一個基本可用的程式 batchrename_basic.py 。這個程式並不完美，但是可以完成最初的任務。注意到 生成編號使用了閉包，這是為了將生成編號的過程抽離出來成為一個可複用的過程，而這個過程無法預知需要生成怎樣的列表，因此每次僅返回一個編號；程式如下：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 |
# -*- coding: cp936 -*- import os import os.path as PathUtil def createDesignator(num, bits): return str(num).zfill(bits) def number_generator(start_num=0, bits=4): start = [] start.append(start_num) def inner(): start[0] = start[0] + 1 return createDesignator(start[0], bits) return inner def batchrename(dir_path, prefix="IMG_",generator_func=number_generator()): ''' rename files (such as xxx.[jpg, png, etc]) in the directory specified by dir_path to [prefix][designator].[jpg, png, etc], designator is generated by generator_func ''' names = os.listdir(dir_path) for filename in names: old_filename = PathUtil.join(dir_path,filename) if PathUtil.isfile(old_filename)==True: newname=prefix.upper() + generator_func() + '.' + getFileSuffix(filename) os.rename(old_filename,PathUtil.join(dir_path,newname)) def getFileSuffix(filename): try: sep_ind = filename.index('.') return filename[sep_ind+1:] except ValueError: return None def testGetFileSuffix(): assert getFileSuffix("good.jpg") == "jpg" assert getFileSuffix("good") is None print "testGetFileSuffix Passed." def testNumberGenerator(): geneNums = [] generator = number_generator() for i in range(10): geneNums.append(generator()) assert geneNums[0] == '0001' assert geneNums[1] == '0002' assert geneNums[9] == '0010' print 'testNumberGenerator Passed.' if __name__ == '__main__': testGetFileSuffix() testNumberGenerator() dir_path = '/home/lovesqcc/setupdir/scitools/pic/mmnet/beauty' batchrename(dir_path, prefix="beauty_") |
健壯性
健壯性體現了程式應對錯誤的能力。一個需要網路連線的 APP 在網路正常的情況下執行流暢，如果沒有網路呢？ 就必須告知使用者先連線到網路才行。或者採用輸入自動糾錯。比如在搜尋引擎裡搜尋 jquery, 不小心寫成了 jqeury 。搜尋引擎會提示是否需要搜尋的是 jquery。在此例中，當路徑不存在時，就會報錯。
|
1 2 3 4 5 6 |
Traceback (most recent call last): File "batchrename_robust.py", line 57, in batchrename(dir_path, prefix="beauty_") File "batchrename_robust.py", line 21, in batchrename names = os.listdir(dir_path) OSError: [Errno 2] No such file or directory: '/home/lovesqcc/setupdir/scitools/pic/mmnet/beauty' |
解決方法很簡單： 將 names = os.listdir(dir_path) 抽離出來，寫成一個函式並進行異常捕獲，然後該行改寫成 names = getDirFiles(dir_path):
|
1 2 3 4 5 6 |
def getDirFiles(dir_path): try: return os.listdir(dir_path) except OSError, err: print 'No Such Directory: %s, exit.' % dir_path os._exit(1) |
可定製性
如果使用者想指定路徑和字首，就必須在程式裡修改並重新部署，顯然是比較“僵硬”的。控制檯程式通常要加上命令列引數，而實際應用則使用配置檔案。下面通過使用 argparse 模組給該程式新增命令列引數，使之具備可定製性。新增一個 parseArgs 方法， 並修改 main 即可。注意到，使用了元組來清晰表達所希望返回的引數格式，便於主程式使用； 魔數均用字串常量來表達，保證可維護性。
使用方式： $ python batchrename_robust_customized.py /home/lovesqcc/setupdir/scitools/pic/fuzhuang/fz2/ -p fz2 -m NUM 1 5
-p, -m 都是可選的。預設只需要指定目錄路徑。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 |
import argparse DEFAULT_PREFIX = 'IMG_' DEFAULT_START_NUM = 1 DEFAULT_BITS = 4 NUM_METHOD = 'NUM' def parseArgs(): description = 'This program is used to batch rename files in the given DIRECTORY to PREFIX_GeneratedDesignator. GeneratedDesignator is a BITS number counting from START_NUM to the number of files (etc. PREFIX0001,PREFIX0002,...) in the given DIRECTORY with leading zero if necessary.' parser = argparse.ArgumentParser(description=description) parser.add_argument('DIRECTORY', help='Given directory name is required') parser.add_argument('-p','--prefix',nargs='?', default="IMG_", help='Given renamed prefix') parser.add_argument('-m','--method',nargs='*',help='method to generate designator, etc --m [NUM [START_NUM [BITS]]]') args = parser.parse_args() dir_path = args.DIRECTORY if args.prefix: prefix = args.prefix else: prefix = DEFAULT_PREFIX if not args.method: method = NUM_METHOD start_num = DEFAULT_START_NUM bits = DEFAULT_BITS return (dir_path, prefix, (method, start_num, bits)) if type(args.method) == list: if len(args.method) == 0: method = NUM_METHOD start_num = DEFAULT_START_NUM bits = DEFAULT_BITS elif args.method[0] ==NUM_METHOD: method = NUM_METHOD if len(args.method) == 1: start_num = DEFAULT_START_NUM bits = DEFAULT_BITS elif len(args.method) == 2: start_num = int(args.method[1]) bits = DEFAULT_BITS elif len(args.method) == 3: start_num = int(args.method[1]) bits = int(args.method[2]) return (dir_path, prefix, (method, start_num-1, bits)) |
|
1 2 3 4 5 6 7 8 9 |
if __name__ == '__main__': testGetFileSuffix() testNumberGenerator() (dir_path, prefix, (method, start_num, bits)) = parseArgs() if method == NUM_METHOD: number_generator = number_generator(start_num, bits) batchrename(dir_path, prefix, number_generator) |
可追蹤性
可追蹤性體現了程式執行過程的可知性和可監控性。記錄程式執行中的關鍵狀態和關鍵路徑，也非常有利於出現錯誤時進行除錯。在此例中，要將檔案重新命名的具體資訊記錄下來，簡便起見，程式中只是列印一下：
|
1 2 |
os.rename(old_filename,PathUtil.join(dir_path,newname)) print '%s rename to %s.' % (filename, newname) # should be info log |
安全性
安全性通常表達兩層含義： 1. 程式絕對不能破壞使用者的資料； 2. 程式必須防止其它程式破壞使用者資料或窺探使用者隱私。其中第一條是不可觸犯的。當我們重複執行 $ python batchrename_robust_customized.py /home/lovesqcc/setupdir/scitools/pic/fuzhuang/fz2/ 時，會驚訝地發現，重新命名後檔案變少了！當執行足夠次後，檔案可能只剩下一個！ 這是怎麼回事呢？ 執行若干次之後，擷取一次結果如下：
|
1 2 3 4 5 |
IMG_0006.png rename to IMG_0002.png. IMG_0003.jpg rename to IMG_0003.jpg. IMG_0002.png rename to IMG_0004.png. IMG_0005.jpg rename to IMG_0005.jpg. IMG_0007.png rename to IMG_0006.png. |
稍作分析即可知道， Python os.rename 在 UnixSystem 上會預設覆蓋已存在的檔案，而 os.listdir 輸出的結果是無序的！ 解決方案也很簡單：先將 os.listdir 輸出的結果排序後再重新命名，即要修改 getDirFiles：
|
1 2 3 4 5 6 7 8 |
def getDirFiles(dir_path): try: filenames = os.listdir(dir_path) filenames.sort() return filenames except OSError: print 'No Such Directory: %s, exit.' % dir_path os._exit(1) |
可複用性
可複用性的關鍵是單一職責原則和介面定義正交。單一職責原則指一個函式或方法僅做一件小事，望名知義；介面定義正交是說每個函式、類介面定義的事情沒有重疊，可以組合實現非常靈活的功能。如果程式具備較好的可複用性，那麼，在擴充套件程式時也會獲得益處，將改動影響區域性化。在編寫程式時應時時考慮抽離出可複用的過程和方法。可複用性也有助於編寫更有效的單元測試。此例中正是遵循可複用性原則來編寫程式，使得每次改動僅涉及一小部分。
可移植性
寫程式是為了更好更廣泛地使用。可移植性需要：1. 檢測操作平臺； 2. 將特定作業系統的符號和特定作業系統的行為替換成平臺無關的。在本例中，要將路徑分隔符 / 修改為 os.sep. Windows下的使用方式： D:>python batchrename.py -d F:picfuzhuangfz2 -p fz2 -m NUM 1 6
|
1 |
batchrename(dir_path+ os.sep +filename, prefix, generator_func) |
可擴充套件性
可擴充套件性體現了程式應對需求變化的能力。對於此例，可擴充套件性體現在四點： 1. 要對目錄的子目錄遞迴重新命名； 2. 要對多個目錄使用不同字首進行批量重新命名；3. 支援不同的編號生成方式；4. 對於非圖片檔案的批量重新命名。 對於第一點，只需要修改 batchrename 方法即可，檢測到如果是目錄，則遞迴呼叫 batchrename ; 對於第二點，則需要修改命令列引數格式，增加 -d 引數，引數個數至少一個；修改 -p 引數，引數可為零到多個。如果給定目錄數大於給定字首，則使用最後一個字首將字首數補足；若給定目錄數小於字首數，則將從後數多餘的字首忽略。要修改 parseArgs 和 main；對於第三點，則要將生成編號的方式抽離成可複用的過程，使得每次僅返回一個編號；對於第四點，由於沒有對檔案型別做判斷，因此也是適合於非圖片檔案的。最終的程式如下所示， 使用方式：
$ python batchrename_robust_customized_extended.py -d /home/lovesqcc/setupdir/scitools/pic/fuzhuang/fz2/ /home/lovesqcc/setupdir/scitools/pic/fuzhuang/fz1 -p fz2 fz1 -m NUM 1 5
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 |
# -*- coding: cp936 -*- import os import os.path as PathUtil import argparse DEFAULT_PREFIX = 'IMG_' DEFAULT_START_NUM = 1 DEFAULT_BITS = 4 NUM_METHOD = 'NUM' def parseArgs(): description = 'This program is used to batch rename files in the given DIRECTORY to PREFIX_GeneratedDesignator. GeneratedDesignator is a BITS number counting from START_NUM to the number of files (etc. PREFIX0001,PREFIX0002,...) in the given DIRECTORY with leading zero if necessary.' parser = argparse.ArgumentParser(description=description) parser.add_argument('-d','--directories', nargs='+', help='Given directory name is at least one required') parser.add_argument('-p','--prefix',nargs='*', help='Given renamed prefix') parser.add_argument('-m','--method',nargs='*',help='method to generate designator, etc --m [NUM [START_NUM [BITS]]]') args = parser.parse_args() dir_path_list = args.directories dir_num = len(args.directories) if not args.prefix or len(args.prefix) == 0: prefix_list = [DEFAULT_PREFIX] * dir_num prefix_num = dir_num else: prefix_list = args.prefix prefix_num = len(args.prefix) if prefix_num > dir_num: prefix_list = prefix_list[0:dir_num] else: prefix_list.extend([prefix_list[prefix_num-1]]*(dir_num-prefix_num)) if not args.method: method = NUM_METHOD start_num = DEFAULT_START_NUM bits = DEFAULT_BITS return (dir_path_list, prefix_list, (method, start_num, bits)) if type(args.method) == list: if len(args.method) == 0: method = NUM_METHOD start_num = DEFAULT_START_NUM bits = DEFAULT_BITS elif args.method[0] ==NUM_METHOD: method = NUM_METHOD if len(args.method) == 1: start_num = DEFAULT_START_NUM bits = DEFAULT_BITS elif len(args.method) == 2: start_num = int(args.method[1]) bits = DEFAULT_BITS elif len(args.method) == 3: start_num = int(args.method[1]) bits = int(args.method[2]) return (dir_path_list, prefix_list, (method, start_num-1, bits)) def createDesignator(num, bits): return str(num).zfill(bits) def number_generator(start_num=0, bits=4): start = [] start.append(start_num) def inner(): start[0] = start[0] + 1 return createDesignator(start[0], bits) return inner def getDirFiles(dir_path): try: filenames = os.listdir(dir_path) filenames.sort() return filenames except OSError: print 'No Such Directory: %s, exit.' % dir_path os._exit(1) def batchrename(dir_path, prefix=DEFAULT_PREFIX ,generator_func=number_generator()): ''' rename files (such as xxx.[jpg, png, etc]) in the directory specified by dir_path to [prefix][designator].[jpg, png, etc], designator is generated by generator_func ''' names = getDirFiles(dir_path) for filename in names: old_filename = PathUtil.join(dir_path,filename) if PathUtil.isfile(old_filename)==True: newname=prefix.upper() + generator_func() + '.' + getFileSuffix(filename) os.rename(old_filename,PathUtil.join(dir_path,newname)) print '%s rename to %s.' % (filename, newname) # should be info log else: batchrename(dir_path+os.sep+filename, prefix, generator_func) def getFileSuffix(filename): try: sep_ind = filename.index('.') return filename[sep_ind+1:] except ValueError: return None def testGetFileSuffix(): assert getFileSuffix("good.jpg") == "jpg" assert getFileSuffix("good") is None print "testGetFileSuffix Passed." def testNumberGenerator(): geneNums = [] generator = number_generator() for i in range(10): geneNums.append(generator()) assert geneNums[0] == '0001' assert geneNums[1] == '0002' assert geneNums[9] == '0010' print 'testNumberGenerator Passed.' if __name__ == '__main__': testGetFileSuffix() testNumberGenerator() (dir_path_list, prefix_list, (method, start_num, bits)) = parseArgs() dir_num = len(dir_path_list) for i in range(dir_num): if method == NUM_METHOD: number_generator_func = number_generator(start_num, bits) batchrename(dir_path_list[i], prefix_list[i], number_generator_func) |
效能成本
程式設計師有追求高效的強迫症。想象這是一個 web 服務， 效能成本通常體現在響應速度和吞吐量。響應速度是使用者可感知的，影響到使用者體驗；吞吐量是使用者不可感知的，影響到服務成本。此例中可以考慮百萬個檔案的重新命名；影響效率的因素有兩個： 1. 檔名排序時間； 2. rename 系統呼叫時間。對於前者，使用快速排序，或者使用更精細的方法在 batchrename 函式中解決 os.rename 預設覆蓋已存在檔案的問題（這樣會降低可維護性）； 對於後者，如果程式設計平臺或系統呼叫提供了更高效的批量重新命名介面，則可批量呼叫該介面來完成任務。
結語
提高程式質量並非一蹴而就，而是可以通過漸進的方式來實現。當實現了一個基本可用的程式時，還處於一個起點，有必要問問自己：
1. 健壯性： 程式需要怎樣的執行環境和輸入引數？ 如果執行環境不滿足或輸入引數不合法，程式該如何應對？
2. 可定製性： 程式有哪些引數或特性是可定製的？ 切忌在程式碼裡寫死；
3. 可追蹤性： 程式有哪些關鍵執行狀態和關鍵執行路徑？ 使用 info 日誌記錄下來；
4. 安全性： 程式在何種情況下可能破壞使用者的資料？ 程式如何禁止非法程式破壞或窺探使用者資料？
5. 可擴充套件性： 程式可能有哪些變化的潛在合理的需求？
6. 可複用性： 函式方法是否臃腫，可以從中抽離出可複用的子過程？
7. 可測試性： 關鍵函式和方法是否有充分的單元測試？
8. 效能成本： 響應速度是否在使用者接受範圍內？是否可以在不降低可維護性的前提下優化區域性，提高整體吞吐量？ 對於大資料量，程式是否可以應對？ 程式的吞吐量極限是多少？