Friday, September 7, 2012

寫註解的要點


"註解是用來寫目的、限制條件跟預期結果等,而不是寫出以下這些程式一行行會做些什麼"

"你要做的事情應該是讓 source code 本身容易了解,而不是透過註解。透過正確的變數命名、好的空白間隔、邏輯分離清楚的執行路徑等手法,我們很少需要在函式裡面註明這些程式在做什麼,我自己的經驗除非是有參考外部的程式碼或複雜演算法,我會多註明參考來源(網址)。"

"Class, module, method 前面是個寫註解的好地方,而且每個語言都有工具(例如 RDoc, Javadoc… 等)可以幫忙從程式碼中整理出好看的純文件,這些說明通常有:
  • Purpose 目的
  • Requirements(pre-conditions) 預期的輸入是什麼
  • Promises(post-conditions) 什麼樣的輸入,會有什麼樣的預期輸出
  • Exceptions: 有哪些例外(exceptions)情況"
寫程式的 edit/build/test 週期要短,加上不斷的重構改進,才會寫出容易閱讀、容易測試的小函式和高內聚力的類別,而不是一大沱複雜無法掌握的程式。




(待補充...)


.

No comments:

Post a Comment