iT邦幫忙

DAY 19
4

程式設計心法系列 第 19

程式設計心法:18.註解行不行

「好的註解讓你讓天堂,差的註解讓你淚兩行」這是我們看程式時,最佳的心情寫照。

註解的重要性可見一般。只是,什麼時候要註解?註解的內容又要有哪些呢?

我們先來看一下書中舉的一個極端的例子:

'*****************************************************************
'* 常式名稱:CopyString
'*   
'* 目的:這個常式從來源字串(Source$)複製字串到目的字串(Target$)
'*
'* 演算法:首先取得 Source$ 的長度,然後每次複製一個字元到 Target$。
'*         它使用迴圈索引值當做存取陣列時的索引值來存取 Source$ 與
'*         Target$ 內的資料,並且在複製完一個字元後遞增索引值。
'*
'* 輸入資料:Inputs$ 要複製的字串
'*
'* 輸出資料:Outpur$ 準備接收複製資料的字串
'*
'* 預設條件:無
'*
'* 程式修改記錄:無
'*
'* 作者:黃小暐
'* 撰寫日期:10/1/92
'* 電話:(222) 555-2255
'* 
'*****************************************************************

如果您看到這種註解,是不是當場傻眼!這樣好像只要閱讀註解就可以知道這個常式在做什麼,很詳細也很清楚!但是這樣到底是寫程式為主還是寫註解為主?

因為我們在閱讀程式的過程中,其實就會了解這段程式所執行的方式,其實是不需要個別去說明的。(這反倒是比較像系統設計文件所撰寫的東西)每次有異動,就會一直累計資料,註解不斷的長大,反倒有點宣賓奪主的味道了。與其這樣,倒不如用 Blog 來記錄開發的過程,查詢也比較方便。

在前面已經介紹了很多程式撰寫時方便閱讀與維護的技巧,程式即是註解,其實就是最高的境界了。但是總是有不足之處,例如是什麼時候修改的?是為了什麼目的修改的?

所以,如果註解能夠扮演著畫龍點睛之妙,則是最佳的模式了。
那麼我們應該怎樣來進行註解?

.宣告的註解
.說明數值資料的單位
.資料所允許的數值範圍
.輸入的條件限制
.為全域變數的功用加註

.標示程式區塊的開始與結束
最常看到的就是 HTML 原始碼中常會出現的標示了。在一般的程式設計中,反倒是比較少這樣做,大部分都只有開頭的註解做區隔而已。

.維護程式時的註記
養成良好的習慣,將維護記錄寫在所修改的程式上方,註記日期、修改者、需求者,甚至如果有需求單的編號,並說明修改的目的,解決的問題。

.著重在「為什麼?」而不是「如何做」
就像一開頭的註解的例子,我們不需要在註解中說明這段程式是如何撰寫的,而是要說明撰寫這段程式碼的目的。

.將註解靠近所需說明的程式
如果我們將註解都像文章開頭一樣,都寫在巨大的註解區塊中,要去了解程式的來龍去脈是會有點困難與花時間的。

其他一些也常會使用的註解方式,羅列如下:
**.在常式的開頭用一、二句話說明常式的功用

[b].說明常式的預設條件**

.保留常式的修改過程

.將註解跟隨程式縮排
保持一貫的程式撰寫風格,即使是註解,也讓他跟著程式一起進行縮排,視覺上會比較美觀有秩序。(一般的開發工具,對於註解是不會自動幫您縮排的)

.以至少一行空白行來區隔註解與程式段落

很多時候,我們會引用網路上的 Open Source 撰寫的程式碼,我們常會發現有以下的註解:

.簡述個別檔案或常式的目的
.作者簡介及聯絡資訊
.版權聲明及授權方式

在引用的時候,為尊重原作者,盡可能將作者的註解一併置入程式中,更好的是,通知作者引用其程式碼,並致感謝之意。

而有些授權方式,是您也要將所修改後的原始碼 Open 出去,這點可能要多留意一下。

本系列文章


上一篇
程式設計心法:17.程式撰寫風格
下一篇
程式設計心法:19.說明文件
系列文
程式設計心法31
0
fillano
iT邦超人 1 級 ‧ 7 年前

其實程式著寫很詳細,有時後是為了使用機器(程式工具)做處理來產生文件。我們以前用這個方式事後補文件...結果SQA要求文件要用Word來寫(這什麼要求?),所以又想辦法把HTML文件用XSLT轉成Microsoft Office XML格式...真是慘痛的經驗。

0
海綿寶寶
iT邦超人 1 級 ‧ 7 年前

註解和系統規格文件有類似的地方

每個人都認為很重要

每個人都不想寫
等到
被要求時
都隨便寫一寫應付了事

0
kbslave
iT邦新手 4 級 ‧ 7 年前

最怕的是程式內容一直改,但註解失去了維護,導致註解與程式內容不一致~
後面的人只看註解不看內容,那就糟糕了...

我個人還是推簡易型註解,就是盡量只爭對下一行CODE做簡單描述...XD

0
pajace2001
iT邦研究生 1 級 ‧ 4 年前

對阿!!錯誤的註解有的時候比沒有註解更慘 XD

我要留言

立即登入留言