第五章實現階段：符式文體的組成元素（Elements of Forth Style）

───────────────────────────────────────

寫得不好的符式程式，有人說看起來像"通過垃圾擠壓機的程式碼"。不錯，那是因為符式在撰寫應用程式的方法上允許更多的自由。然而，若能細心地運用良好符式文體中的這些元素，則那份自由也能讓我們有機會寫出可讀性高、又容易維護的程式碼。本章要深入探討符式在"寫碼"（coding）上的一些約定（convention），其中包括：

程式列表的組織（Listing organization）幕的配置，間隔及縮排（Indentation）註解命名

我希望能推薦一份「放諸天下皆為準」的約定給每一個人。不幸的是，這樣的一份清單，在很多情況下不見得都是適用的。本章將許多廣被採用的約定和個人的偏好揉合在一起，並附上其它的見解和這些偏好的理由。換句話說：

      : 提示   價值  評斷  ;

特別要感謝Kim Harris先生。本章所提到的約定，多半是由他所建議的。更感謝他在對優良符式文體的一些分岐看法上，鍥而不捨地所作的統一整合的貢獻。
程式列表的組織

組織良好的書，必定有定義清晰的章節，及一份完整的目錄，使你能一眼便看出全書的組織。一本組織良好的書，比較容易讀。一本組織不良的書則難懂，日後查閱資料也會很困難。這種良好組織的需求，也同樣適用在程式的列表上。良好的組織涉及下列三方面：

1. 拆解（Decomposition） 2. 組合（Composition） 3. 檔案分區
拆解

正如我們所見，一個程式列表的組織，應該對應著應用程式拆解而成的詞集。一般而言，這些詞集應該依照"使用上"的順序，依次排列。"被使用"的詞集應該排在"使用"它的詞集之前。大體上，程式列表中的元素應該按照它們的複雜度來編組，最複雜的東西出現在最後面。事情最好能被安排到一種程度，使你能夠空著最後的一些幕不用（也就是，不要載入它們），仍然能有個自足的、能夠跑的正常的應用程式，只是缺少一些最高級的功能而已。（譯註：傳統上的符式系統，其原始程式都儲存在一種以1K字元為單位的"冪"中，而不是一般格式的文字檔。）在第三章中，我們已經充份地討論了拆解的藝術。
組合

組合是將各個單件揉合在一起，以產生一個整體。良好的組合正如同良好的拆解，也需要各種技巧。符式現行的約定之一是，原始碼（source code）被存放在"幕"（screen）中，它是一個1仟字元的儲存單元。（此處所說的"幕"係指專供原始碼所使用的一個區塊）。在符式中，若祗是單純地將每一幕串接起來，讓整個程式的列表看起來像一本長串的折疊式手冊，這雖然辦得到，但卻不是個好方法。反而：

─────────────────────────────────────
提示要像一本書一樣的編排你的應用程式列表，使它們層次分明。
─────────────────────────────────────

一個應用程式可能含有：

幕（screens ）：符式原始碼的最小儲存單位詞集（lexicons）：包含一到三幕，能夠實現一個元件章節（chapters）：一系列相關的詞集載入幕（load screens）：類似一個目錄，能將章節按適當的次序載入

      圖 5-1  應用程式的載入幕之一例

      Screen # 1                                        07/09/83
        \ QTF+ Load Screen
        : RELEASE#   ." 2.01" ;
          9 LOAD  \ compiler tools, language primitives
         12 LOAD  \ video primitives
         21 LOAD  \ editor
         39 LOAD  \ line display
         48 LOAD  \ formatter
         69 LOAD  \ box
         81 LOAD  \ deferring
         90 LOAD  \ framing
         96 LOAD  \ labels, figures, tables
        102 LOAD  \ table of contents generator

     圖5-1為一個應用程式載入幕的例子。由於它被安排在第一幕，你可以鍵入下式以將整個應用程式載入：

      1  LOAD

這幕中的各個命令會將應用程式的各個章節載入。譬如，第12幕即為視頻基元這一章的載入幕。
作為一種參考工具，應用程式的載入幕能告訴你在何處找到各個章節。譬如你若想查看那負責畫框（framing）的常式，就會發現該章是從第90幕開始的。
每一章節各自的載入幕，會再將組成該章的全部的幕載入。我們即將學到如何規劃章節的載入幕。
這種階層式體系最直接的好處在於，你能夠個別地載入任何章節或任何幕而不必非載入整個應用程式不可。「原始碼的模組化」是符式能快速地處理「編輯、載入、測試」整個過程的主要理由之一（這也是「反覆接近法」所需要的）。正如一本書的每一頁一樣，每一幕都可以被個別而快速地存取。在原始碼的維護上，它也正是一種"隨機存取"（random access ）的方法。
你也可以將程式碼中的任一節，以一個新的、試驗用的版本來取代，唯一要做的只是在載入幕中將幕號改掉即可，而不必在檔案中將大量的碼移來移去。
在小型的應用程式中，你可能根本用不到章節這種東西。這時，應用程式的載入幕可以直接地載入所有的詞集。但是，對於大型的應用程式，這額外的層次卻有助於可維護性。
一個幕可以是載入幕或者是程式碼，但不要是兩者的混合。要避免僅僅因為你"需要某種東西"，或者因為你"用完了冪的空間"，而在一個含有一些定義的幕中嵌入一個LOAD 或 THRU 的載入命令。
　

跳過（Skip）命令

有兩個命令，可以使一幕中何者該載入、何者該忽略的控制變得容易些。它們是：

      \
      \S

『\』讀作"skip-line"（跳行）。它會使符式解譯器跳過這行中在它右邊的全部文句。（『\』是個符式字，它的左右必須有空格做分隔）。它運作時並不需要界限符號（delimiter）。在圖5-1中，你能見到『\』的兩種使用方式：用來起始這一幕的註解行（第0行），以及各行的註解 --當右邊不再出現程式碼時。在測試時，『\』也常被用來將「含有括號的名字或註解」的一些行暫時地"註解"掉。例如，藉著下面兩個『\』，可以使『NUTATE』這個字的定義免於被編譯，也免除了當遭遇到行中的右括弧時，所產生的困擾：

      \ : NUTATE  ( x y z --)
      \   SWAP ROT  (GET) ;

『\S』讀作"skip-screen"（跳幕）。它會使符式解譯器跳過它所在的那一幕中，在它之後的所有東西。有關『\』及『\S』的定義請參考附錄C 。
章節載入幕（chapter-load screen）

      圖 5-2  章節載入幕之一例

      Screen # 100
         \ GRAPHICS              Chapter load               07/11/83
          1 FH LOAD         \ dot-drawing primitive
          1 FH 3 FH THRU    \ line-drawing primitives
          4 FH 7 FH THRU    \ scaling, rotation
          8 FH LOAD         \ box
          9 FH 11 FH THRU   \ circle

          CORNER  \ initialize relative position to low-left corner

圖5-2所示為一標準的章節載入幕。此幕所載入的幕號都是相對的，這與應用程式的載入幕中所用的不同，在那裡使用的是絕對幕號。
這是因為章節載入幕是一個章節中，一連串幕的第一幕。你可以將整章的內容在程式列表中前後移動；在章節載入幕中所使用的相對指標，不會因章節所在的位置不同而改變。所必須改變的僅僅是應用程式載入幕中，指著該章節載入幕的那一個數值而已。

─────────────────────────────────────
提示應用程式載入幕中使用絕對幕號。在章節的載入幕中則使用相對幕號。
─────────────────────────────────────

實現相對載入的方式有兩種。最常用到的字是：

      : +LOAD   ( offset -- )   BLK @ +  LOAD ;
    ~FB7BX1BB1;及~I;
      : +THRU   ( lo-offset hi-offset --)   1+  SWAP DO  I +LOAD  LOOP ;

依我自己的方式，只需要用單一個字『FH』。（我認為它是一種較好的分解，其定義請參閱附錄C ）。片語

      1 FH LOAD

應讀作"1 From Here LOAD"（意指：從此處算起的第一幕開始載入），其作用與『1 +LOAD』相同。同樣的，

      2 FH  5 FH THRU

應讀作"2 From Here, 5 From here THRU" 。有些程式設計師在每一章的起始處都使用一個傀儡字（dummy word），例如：

      :  VIDEO-IO  ;

並且在應用程式載入幕中，該章的載入命令處註解著列出這個名字。這樣就容許能選擇性地"忘掉"任何章節，再重新由那一點起載入，而不必費事的去查閱那一個章節的內容。在一章開頭的一些幕中，通常被用來定義此章節中共同使用的變數、常數、及資料結構。接下來才是詞集，依著"使用上"的順序載入。章節載入幕的最後一行通常會呼叫所需要的初始命令（initialization command）。（譯註：但是在TURNKEY的系統中，初始命令必需在程式執行後才進行，而不是在載入時進行。）某些很在意文體的符式寫作者，總喜歡以一篇"前言"開始。其中以平常的用語來討論該章中元件的運作原理。圖5-3是這類前言的一例，其中示範Moore產品公司所要求的格式。

      圖5-3  Moore產品公司對章節前言的規格

        CAHPTER 5  --  ORIGIN/DESTINATION  --  MULTILOOP BIT ROUTINES

        DOCUMENTS  --  CONSOLE STRUCTURE CONFIGURATION
                DESIGN SPECITICATION
                SECTIONS  --  3.2.7.5.4.1.2.8
                              3.2.7.5.4.1.2.10

        ABSTRACT  --  File control types E M T Q  and  R  can all
                      originate from a Regional Satellite or a
                      Data Survey Satellite.  These routines allow
                      the operator to determine whether the control
                      originated from a Regional Satellite or not.

        CHAPTER NOTES  --  Whether or not a point originates from
                              a Reginal Satellite is determined by
                              the Regional bit in BITS, as follows:

                              1 = Regional Satellite
                              2 = Data Survey Satellite

                              For the location of the Regional bit
                              in BITS, see the Design Specification
                              Section - 3.2.7.5.4.1.2.10

        HISTORY  --      ..... ...

───────────────────────────────────────
Charles Moore（符式創始人，與Moore產品公司無關）並不像我那麼看重階層式的程式列表。Moore說：

我會階層式地建構我的應用，但並不一定會用同樣的方式建構我的程式列表。我的程式列表都是以相當鬆散的方式組織而成，並不是基元字（primitives）在前的那種階級觀念。
我使用『LOCATE』（有時也稱為『VIEW』；參閱Starting FORTH一書第九章中的提示）。結果是，程式列表以一種漫不經心的方式組織而成，因為我有『LOCATE』來為我找出我所要的東西。我幾乎從來不去查閱程式的列表。
───────────────────────────────────────

--> 對 THRU

談起"相對載入"的問題，有一種相當流行的方法被用來載入一系列連續的幕，其中所用的字是『-->』（讀作"next block" ）。此字會使解譯器立即停止對當前的幕的編譯，並開始編譯下一幕。若你的系統提供這種『-->』，你就必須在你的章節載入幕中選擇，要使用『THRU』命令來載入一系列的幕呢？或者藉著『-->』將所有的幕連接起來，而僅僅去載入這一系列的第一幕。（你不能兩者都用；這樣會使大部份幕都被載入兩次或兩次以上。）箭頭的好處是：如果你要在這系列的幕中改變其中一個幕的內容，然後再載入這一幕，這系列中跟在它後面的其餘幕也會自動地被載入。你用不著知道最後一幕在那裏。但這也是箭頭難纏的一面：載入程序一旦開始，你就無法將它停下。為了要單獨地測試其中一幕，你或許會編入一大堆不相干的幕。讓我們對這點做個分析。我們假設，在對那一幕做完了必需的修改之後，你可能會做下列的三件事情之一：

1. 僅僅載入該幕，去測試修改的部份。 2. 載入該幕所在的整個一章。 3. 載入整個應用程式的其餘部份。

『THRU』的使用似乎能給你最大的控制權。有人認為，箭頭是為了那跨出了幕的底界的那種定義而設的。其實，箭頭是編譯那種跨越了一個以上的幕的冒號定義的唯一辦法，因為『-->』是個"立即字"。然而，讓一個冒號定義跨出幕的底界，就絕不會是一個好文體。（它們永遠不該有那麼長！）從另一方面看，在使用組合語言定義的撰寫中，一個極端複雜而又具執行速度需求的定義就很可能要佔據著幾個連續的幕。但即使是這種情況，正常的『LOAD』也已足以應付，因為編譯一個組合語言定義時，系統並未進入編譯模式，因此也就不需要"立即字" 的幫助。
另一種作法：將原始碼儲存在命了名的檔案中（named file）

某些符式業者鼓吹，要以不定長度、取了名字的文字檔來儲存原始碼，刻意地去模仿傳統編譯器及編輯器的做法。這種做法將會日趨普遍，但其用途卻頗值得商榷。不錯，能免除對幕的空間不足的憂慮固然是好事，但是在一個受限制的區域中書寫程式的不便，卻能被「保有對個別的程式區塊（discrete chunks of code）的控制權」所補償。在應用程式的發展中，你花費在"載入"的時間，遠比你用在重新安排幕的內容上，多得太多了。 "無限長"的檔案允許漫不經心、雜亂無章的思想及拙劣的分解作法。定義會愈趨冗長，因為再也沒有那1K區塊的疆界約束。這種傾向會趨於寫出一個20K的檔案，甚至更糟：一個20K的定義。也許一種較佳的妥協是：一個以檔案為基礎的系統，它允許巢式的載入，同時也鼓勵使用非常小的檔案。通常，越有經驗的符式程式設計師，越不太會使用長度超過過5K至 10K的檔案。所以，又有什麼好處呢？面對這種爭議性的問題，有人會說：「記一個名字總比記數字容易嘛。」若果真如此，那麼何不將那些區塊的編號先定義為常數，譬如：

      90 CONSTANT FRAMING

然後要載入"Framing"的章節時，就鍵入

      FRAMING LOAD

或者，要列出該章節的載入幕的內容時，就鍵入

      FRAMING LIST

（在章節名稱的尾端加"ING"也是一種約定。）當然，若想將以幕為基礎的方式所引發的不便減到最低，你需要一些良好的工具，包括能夠讓你很容易地將原始碼從一幕搬到另一幕的編輯命令；也包括一些能將一群幕在程式列表中前後移動的命令。
檔案分區

要得到組織良好的程式列表，最後一個重點涉及到檔案內部使用上的安排 --什麼資料該放到檔案上的什麼位置。這種標準必須依各個工廠、各部門或各個程式設計師，視其工作的性質不同而訂定。

      圖 5-4  某部門的檔案分區做法

      Screen 0 is the title screen, showing the name of the
         application, the current release number, and primary author
.本文g2
      Screen 1 is the application-load block
.本文g2
      Screen 2 is reserved for possible continuation from Screen 1
.本文g2
      Screen 4 and 5 contain system messages
.本文g2
      Screen 9 thru 29 incorporate general utilities needed
         in, but not restricted to, this application
.本文g2
      Screen 30 begins the application screens

圖 5-4顯示一個典型部門的檔案分區做法。
很多符式廠商都認為，程式碼的各章節應起始於可被3整除的幕號上。檔案中主要的分段區隔應該起始於可被30個幕整除的界限上。
理由何在？在習慣上，符式是以3幕一頁的方式印出，最頂端的幕號總是要能被3整除。這樣的一頁叫做一個"triad"（三幕組）；多半的符式系統均已將『TRIDE』一字納入其中。它的功能是，給它一個三幕組中任一幕的編號做引數，它就能產生這頁的列表。
例如，你若鍵入

      77 TRIAD

你就會得到包括75, 76, 及77三幕的一頁。
這種約定主要的好處在於，如果你改變某單一個幕的內容，你可逕自將新印出的一頁插入你的程式列表夾中，換掉原有的那頁，而不會造成程式列表資料的重疊或缺少。

─────────────────────────────────────
提示讓各節或各詞集起始於可被3整除的幕號上。讓應用程式或各章起始於可被30整除的幕號上。
─────────────────────────────────────

選件（electives）：能選擇性地加入的功能組件

符式的系統廠商有個問題。如果他們將客戶所期望的每一個命令 --諸如控制繪圖機、列表機、或其它週邊設備所用的字-- 都包含到他們的系統中，系統就會吃掉電腦記憶容量的半數以上，剩餘的空間就不足以讓真正在意的程式設計師在編寫應用程式時施展身手。解決的辦法是讓廠商祗提供一個骨架，做為一種事先編譯好的核心。額外的好東西則以原始碼的形式供應給使用者。這種辦法容許程式設計師挑選那些他真正需要的特殊功能。這種由使用者載入的常式稱為"選件"。雙整數運算，日期時間的支援，條件分枝（CASE）敘述以及 DOER/MAKE 的建構（後文將有交代）都是符式系統應該以選件方式提供的功能之一。
幕的配置（screen layout）

本章將討論幕（source screen）的配置。

─────────────────────────────────────
提示留下第0行做為 "註解行"。
─────────────────────────────────────

註解行既可在幕中作為標題，又可做為檔案中的『INDEX』行。它應該描述出該幕的目的，而非列出此幕中所定義的字。註解行至少要含有此一幕的名稱。在大型的應用程式中，你可能將章節及幕的名稱一併納入。若此幕是實現某個詞集的一群幕中的一個，你也應該安排一個"頁號"（page number）。右上角是留作"簽章"（stamp）之處。"簽章"應該包括最近一次的修版日期。若作者是何人也是重要的，他的姓名字首（三個英文字母，排於日期左方）也應包括在內；例如：

      ( Chapter name            Screen Name -- pg #         JPJ 06/10/83)

某些符式編輯器只需按一個鍵，就能替你簽章完畢。代表日期的一般形式如下：

      mm-dd-yy

例如1984年2月6日應寫為

      02-06-84

逐漸流行的另一種寫法是

      ddMmmyy

其中的Mmm為月份三個字母縮寫，例如

      22oct84

上式雖比下式多幾個字母

      10-22-84

卻可避免日期與月份的混淆。若你的系統中有『\』這個字，你可以將註解行寫成：

      \ Chapter name           Screen Name -- pg.#         JPJ 06/10/83

對所有的註解而言，使用小寫字母或大小寫混用均可。為了使『INDEX』命令能披露更多有關應用程式幕的編組情形，辦法是在一個詞集的連續幕中，將其註解行的起始點縮排（indent）三格。圖5-5所示係由『INDEX』所產生的列表的一部份，其中，連續幕的註解行已被後移三格。

      圖5-5  INDEX的輸出，並顯示縮排後的註解行

      90 \ Graphics           Chapter load         JPJ 06/10/83
      91 \ Dot-drawing primitives              JPJ O6/10/83
      92 \ Line-drawing primitives             JPJ O6/11/83
      93    \ Line-drawing primitives          JPJ O6/10/83
      94    \ Line-drawing primitives          JPJ O9/02/83
      95 \ Scaling, rotation                   JPJ O6/10/83
      96    \ Scaling, rotation                JPJ O2/19/84
      97    \ Scaling, rotation                JPJ O2/19/84
      98    \ Scaling, rotation                JPJ O2/19/84
      99 \ Boxes                               JPJ O6/10/83
     100 \ Circles                             JPJ O6/10/83
     101    \ Circles                          JPJ O6/10/83
     102    \ Circles                          JPJ O6/10/83

─────────────────────────────────────
提示所有的定義應該從幕的左緣開始寫，而且每行只定義一個字。
─────────────────────────────────────

劣：

      :  ARRIVING    ." HELLO"  ;    :  DEPARTING   ." GOODBYE"  ;

優：

     : ARRIVING   ." HELLO" ;
     : DEPARTING   ." GOODBYE" ;

這個約定方便於在程式列表中找出某個定義。（當定義的長度超過一行時，下一行的起始必須後移。）

變數及常數也應該是每行一個定義。（參閱附錄E，良好註解的文體）這樣就能留下空間供註解使用。例外的情況是定義一組"家族字"的時候（由同一個定義字所定義出），它們不需要個別的註解。

      0 HUE BLACK     1 HUE BLUE     2 HUE GREEN
      3 HUE CYAN      4 HUE RED      5 HUE MAGENTA

─────────────────────────────────────
提示要在幕的底部預留空間，供爾後添加新定義之用。
─────────────────────────────────────

在第一輪（pass）的寫作中，每一幕不要使用超過一半的空間。「反覆作為」需要你先寫出應用程式元件的骨架大綱，然後再反覆地不斷添加肌肉，直到所有的需求都被滿足為止。通常，這意味著你要對目前存在的幕，加入新的命令，或加入例外狀況的處理。（有時，但機會不多，一次新的反覆作為，或許會發現程式碼可以被簡化；或許會發現，某一繁複的情況實際上是屬於另一個元件，應該將它分解出來，移到另一幕中。）若在最初就留有餘地，就會使爾後的添加行動較為愉快。有一位程式設計師建議，在第一輪中，應該使程式碼只佔有一幕的20-40％，留下80-60％的空白[1]。不要在各個定義之間留下空行。但在兩群定義之間留下空行則是合理的。

─────────────────────────────────────
提示所有的幕在結束時，必須回到10進制下。
─────────────────────────────────────

即使你有三個以16進制寫出的連續的幕，在各個幕的起頭，你仍應將『BASE』（基底）設定為『HEX』，並在幕底再設回『DECIMAL』。此一約定的主要目的是為了確保在測試時，各個幕可以個別的載入，而不致弄亂事情。同時在你閱讀程式列表時，也能確定：除非在幕中特別指明是在『HEX』之下，否則數值一律都是10進制的。有些廠商將這項規定擴展的更遠。他們並不在幕底將『BASE』轉回10進制，而是將它設定成與進入這幕時的進位制相同。這種特別的保證可以用下列方式達成：

      BASE @     HEX    \ save original BASE on stack
      0A2 CONSTANT BELLS
      0A4 CONSTANT WHISTLES
      ... etc. ...
      BASE !            \ restore it

有時，一個引數可以從一幕傳送到下一幕。例如在一個跨越多個幕的組合語言定義中，由『BEGIN』或『IF』所傳回的值，或者從某個定義字傳送到另一個定義字的地址（參閱本書第六章中，"編譯時區的分解"一章）。在這種狀況下，最好將『BASE』的值儲存在返回堆疊上，例如：

      BASE @ >R     HEX
      ... etc. ...
      R> BASE !

有人將這種作法當作是一種政策，並使用在『BASE』可能改變的任何幕上，這樣他們就再也不必為它煩心了。 Moore寧可將『LOAD』定義為：在載入之後，自動呼叫『DECIMAL』。這種做法簡化了幕的內容，因為你不必再費心地去重設。
間隔及縮排（Spacing and Indentation）

─────────────────────────────────────
提示間隔及縮排與可讀性息息相關。
─────────────────────────────────────

本書中的例子，使用著大多數人都接受的間隔與縮排的體裁約定。空格若能被恰當的使用，可讀性就能大大的增強。在原始程式幕中留出些空格，除了用掉一些磁碟空間外，絕無害處 --反正它很便宜。對於那些偏愛白紙黑字約定的人，表5-1是一些指引的列表。（但請記住，符式的解譯器是不在乎間隔與縮排的。）

      表 5-1  縮排及間隔的指引

───────────────────────────────────────
空1格 --冒號與名字之間空2格 --名字與註解之間✽ 空2格或換行 --註解之後及定義之前✽ 空3格 --名字與定義之間（若未使用註解時）縮排3格 --用於各後續行（或以3的倍數用於巢狀縮排）空1格 --用於片語內部的字（或數值）之間空2或3格 --用於各個片語之間空1格 --用於最後一個字與分號之間空1格 --用於分號與『IMMEDIATE』（若用到它）之間

定義與定義之間不要留空行，除非是為了分隔兩群不同的定義時。

✽常見的另一些約定要求在名字與註解之間空1格，註解與定義之間空3格。更自由的做法是在註解的前後都空出3格。不論閣下選用的是何種約定，務必保持用法上的一貫性，不要變來變去。
───────────────────────────────────────

每行的最後應該是個空白，除非是：

a) 延續到下一行的字串（quoted string），或 b) 註解的結尾

一個以『\』為起始的註解可一直延續到行尾。同樣的，一個以『(』為起始的註解，它的結束右括號可以是在一行的最末端。下面是常見的間隔與縮排上的錯誤：

劣（名字與身體沒有分開）：

      : PUSH HEAVE HO ;

優：

      : PUSH   HEAVE HO ;

劣（延續的行沒有縮排3格）：

      : RIDDANCE  ( thing-never-to-darken-again -- )
      DARKEN  NEVER AGAIN ;

優：

      : RIDDANCE  ( thing-never-to-darken-again -- )
         DARKEN  NEVER AGAIN ;

劣（片語沒有分隔）：

      : GETTYSBURG   4 SCORE 7 YEARS + AGO ;

優：

      : GETTYSBURG   4 SCORE  7 YEARS +  AGO ;

片語分隔是屬於主觀上的藝術；我一直祈盼能有一套有用的正式規則出現。無論如何，你祗要注意保持著有良好的可讀性就對了。
註解的約定（Comment Conventions）

註解的適當與否事關緊要。註解有五種型式：堆疊效果註解，資料結構註解，輸入字串註解，目的註解及敘事註解。「堆疊效果註解」被用來顯示出這個定義所消耗的、及所傳回的堆疊引數。「資料結構註解」用來顯示資料結構中各元素的位置及含意。例如，一個本文緩衝區可能在第一個字元處存放著一個計數值（count），再接著63個儲存本文用的字元。「輸入字串註解」用來顯示這個定義從輸入字串中所盼望見到的是何種字串。例如字『FORGET』，它會到字典中去找尋輸入字串中的一個名字。「目的註解」是以儘可能少的文句，去描述某一個定義為何被做出來。至於怎麼做出來的，就不是這個註解所要說明的了。「敘事註解」若出現在定義中，是用來解釋正在進行中的事情。通常是逐行的解釋著。敘事註解只被使用在"垂直格式"的程式碼中，這點在稍後會有交代。註解通常以小寫字母寫出，以便與原始程式碼有所區別。（符式字多半是以大寫字母命名的，小寫字母偶爾也會在特例中使用。）下面各節，我們會將上述各型註解的標準化格式做一個總結，並舉出一些實例。
堆疊註記法（Stack Notation）

─────────────────────────────────────
提示每一個涉及到消耗和傳回堆疊引數的定義，都必須含有一個堆疊效果的註解。
─────────────────────────────────────

所謂"堆疊註記法"係指「如何表示堆疊上有什麼」的有關約定。堆疊的註記有三種形式，即"堆疊圖像"，"堆疊效果"及"堆疊效果的註解"。
堆疊圖像（Stack Picture）

堆疊圖像是用來指出在某一時刻，根據對此定義的了解，應該會出現在堆疊上的項目。這些項目依序從左到右列出，最右項代表堆疊的頂端，左項代表較低的位置。例如，堆疊圖像

      n1 n2

指出堆疊上有兩個數值，其中n2在項端（最常被存取的位置）。這也是你鍵入這些數值的順序；例如，若n1為100 ，n2為5000，你會鍵入

      100 5000

來將這些數值正確地放到堆疊上。堆疊圖像可以使用縮寫，例如n1，或完整拼出的字來說明。比較常用的是縮寫。表5-2所列的是一些標準的縮寫。不論使用那種方式，各堆疊項目之間應該留有一空格。若一個堆疊項目需要以片語來描述（如"address of latest link"），片語中所用的字應該以連字符號相接。例如堆疊圖像：

      address current-count max-count

顯示堆疊上有三個元素。

堆疊效果（Stack effect）

一個"堆疊效果"包含兩個堆疊圖像：一個是被定義所使用（消耗掉）的那些項目；另一個是被定義所傳回的那些項目。那"之前"（before）的圖像先出現，其後跟著兩個連字符號，然後為"之後"（after）的圖像。例如符式的加法運算子『+』，其堆疊效果為

      n n -- sum

『+』用掉兩個引數，並傳回它們的和。請記住，堆疊效果僅僅是描述出堆疊運作的"淨結果"。其它一些存留在這些項目之下，與這個定義無關的堆疊項目，則不必顯示出；同樣的，在這個字的執行中，會出現而又消失的項目也不必被顯示出。被用到，但卻末被改變的輸入引數，也應該要重複出現在圖像中；例如：

      3rd 2nd top-input -- 3rd 2nd top-output

反過來說，若改變了任何引數，堆疊的註解就必須使用一個不同的描述符號：

      n1 -- n2
      n -- n'

堆疊效果的註解（Stack effect comment）

一個"堆疊效果的註解"是出現在原始程式碼中，由小括號圍起的一個堆疊效果。下面是『COUNT』一字的堆疊效果註解：

      ( address-of-counted-string -- address-of-text count )

或

      ( 'counted-string -- 'text count)

（當『COUNT』一字執行後，"count" 就會被留在堆疊的頂端。）若一個定義在堆疊上沒有產生效果（也就是說，不論定義的內部發生何等大事，使用者並末查覺到。），它就不需要堆疊效果的註解：

      : BAKE   COOKIES OVEN ! ;

或者，你可以使用一個空的堆疊註解，例如

      : BAKE  ( -- )  COOKIES OVEN ! ;

來強調這個字對外在的世界，並沒有使用或產生任何的堆疊引數。若一個定義只消耗掉一些堆疊引數，卻未傳回任何引數，雙連字符號則可有可無。例如，

      ( address count -- )

可以被簡化成

      ( address count )

（譯註：但是後者的做法缺少一致性，也容易產生困擾。）
　

堆疊縮寫的標準

在堆疊註記中使用的縮寫符號應力求一致。表5-2列出常用縮寫。（此表將在附錄E中再現。）其中所謂"單長度"、"雙長度"等術語是指一個特定的符式系統中"胞元"（cell）的長度。（若系統使用16位元的胞元，則"n"代表一個16位元的數值；若系統使用32位元的胞元，則"n"代表一個32位元的數值。）

                       表 5-2  堆疊註解的縮寫

───────────────────────────────────────
n single-length signed number 單長度，有正負號的數字 d double-length signed number 雙長度，有正負號的數字 u single-length unsigned number 單長度，無正負號的數字 ud double-length unsigned number 雙長度，無正負號的數字 t triple-length 三倍長度 q quadruple-length 四倍長度 c 7-bit character value 7位元的字元值 b 8-bit byte 8位元組 ? boolean flag; or; 布氏旗標；或 t= true 真 f= false 假 a or adr address 地址 acf address of code field 執行區地址 apf address of parameter field 參數區地址 ' (as prefix) address of （做為字首時的）某物的地址 s d (as a pair) source destination （成對出現時）來源及目的的地址 lo hi lower-limit upper-limit (inclusive) 上限及下限（含） # count 計數值 o offset 偏移值 i index 索引值 m mask 遮罩 x don't care (data structure notation) 可忽略--（資料結構表示法）一個"偏移值"是以絕對單位（例如位元組）表示的差量。一個"索引值"是以邏輯單位（例如元素或欄位）表示的差量。
───────────────────────────────────────
　

旗標的註記法

表5-2中顯示三種表示布氏旗標（boolean flag）的方式。為了說明，下面是同一個字『TEXT』的堆疊註解的三種版本：

      ( a1 u a2 -- ?)
      ( a1 u a2 -- t=no-match)
      ( a1 u a2 -- f=match)

跟在"t"及"f"之後的等號，表示執行後旗標所代表的結果。第二種寫法中的右邊應讀成 "true means no match."（旗標為真時，表示沒有吻合的文字存在）。
可能有不同結果的註記法

某些定義在不同情況下會產生不同的堆疊效果。若堆疊上的引數數目在各種狀況下都保持不變，而引數本身卻會變，你可以用垂直線（|）來表示"或者"的意思。下面的堆疊效果註解是描述一個字，它可能會傳回一個檔案的地址（若找到所要的檔案），也可能傳回一個零（表示檔案沒找到）：

      ( -- address | 0=undefined-file)

若某一個堆疊圖像中的引數數目是可變的 --不論在"之前"或"之後"的圖像中 --你就必須使用雙連字符號，並且以 | 符號分開，將兩種版本的全部堆疊圖像都寫出來。例如：

      -FIND   ( -- apf len t=found | -- f=not-found )

此註解顯示：若能尋獲所要的字，則有三個引數會被傳回（真旗標在頂端）；不然，則只有一個假旗標被傳回。高興的話，你可以將整個堆疊效果寫兩次。如果是寫在同一行中，則間隔三個空格：

      ?DUP    \ if zero:( n -- n)     if non-zero:( n -- n n)

或垂直式的列出：

      -FIND  \     found:( -- apf len t )
             \ not-found:( -- f )

  資料結構的註解

資料結構註解是用來描述資料結構中的元素。例如，下面是名稱為『|INSERT』的插入緩衝器（insert buffer）的定義：

      CREATE  |INSERT   64 ALLOT       \  { 1# | 63text }

其中的大括號用來表示這種註解的開始與結束；垂直線作為結構中各元素的分隔符號，數字代表每一元素所佔有的的字元數。在上面的註解中，第一字元是一個計數值，其後跟著63個字元的本文。 "位元的註解"與資料結構註解使用的格式相同，它用來描述某一位元組（或胞元）中各個位元的意義。下面的位元註解

      { 1busy? | 1acknowledge? | 2x | 6input-device | 6output-device }

描述某一通信頻道的狀態暫存器（16位元）的格式。最前的兩位元為旗標，跟著兩個末被使用的位元，最後為一對6位元的欄位，顯示此一頻道所連接的I/O狀態。若有超過一個以上的資料結構使用著相同的圖樣模式，你只須寫出註解一次（很可能是寫在前言中），並付予它一個名稱以便在後續的幕中使用。例如在前言中，若給了上面那種位元圖樣一個"status"的名稱，則"status"就可以被用在堆疊註解中，表示這樣的圖樣：

      : STATUS?  ( -- status) ... ;

如果一個『2VARIABLE』存著一個雙整數值，那麼它的註解就應該是一個能說出它內容的堆疊圖像：

      2VARIABLE PRICE    \ price-in-cents

如果一個『2VARIABLE』含有二個單整數的資料（合在一起恰好是個雙整數），你就該這樣地說明它的堆疊圖樣：

      2VARIABLE MEASUREMENTS  ( height weight )

這與『MEASUREMENTS』是經由使用『CREATE』所定義出時的註解方式不同。

      CREATE MEASUREMENTS  4 ALLOT   \ { 2weight | 2height }

（當兩種述敘在字典中產生相同的結果時，『2VARIABLE』的使用，暗示著它通常是被『2@』與『2!』二字所運作 --因此我們就使用堆疊註解。其中高位的部份（high-order part），也就是會出現在堆疊頂端的，被列在右邊。『CREATE』的使用，卻暗示它的值會被分開著存取 --因此我們使用資料結構的註解方式。其中第0個元素列在最左方。）

輸入字串的註解

輸入字串註解是用來說明，有什麼字或字串是應該出現在輸入字串中的。表5-3列出說明輸入字串引數的用字。

表5-3 輸入字串註解的用字

───────────────────────────────
c 單一字母，以空格分隔 name 一串字母，以空格分隔 text 一串字母，不是以空格分隔 text 後面應跟隨所需的界限符號，例如 text" 或 text)
───────────────────────────────

輸入字串的註解應該出現在堆疊註解之前，而且不要被它自己的一對括號框起，僅在前後各留三個空格。下面即為『 '』定義的註解；輸入字串註解先出現，然後是堆疊註解：

      : '   \   name   ( -- a)

你若偏愛使用 "(" ，註解的寫法就變成：

      : '   (   name   ( -- a)

接受字串的輸入，有三種不同的情況。為避免混淆，它們的說法是：

‧ 搜尋（Scanning-for）：向前找尋輸入字串中的某一個字或數值，例如在『 '』的情況；或是找一個界限符號，例如在『."』及『.(』執行時。 ‧ 期望（Expecting）：在等待著。例如『EXPECT』及『KEY』二字就是在等待輸入。 ‧ 認為（Presuming）：在正常情況下，某些東西應該會跟著出現。例如『:』會搜尋那個要被定義的名稱，並且"認為"它的定義會跟著出現。

輸入字串的註解僅適用於當輸入字串需要被"搜尋"時，才是恰當的。
目的註解（purpose comments）

─────────────────────────────────────
提示每一個定義都必須有一個目的註解，除非： a. 它的目的可由它的名稱或它的堆疊註解清晰的看出時，或者 b. 如果它是由三個以下的字所組成的。（簡單到不需任何註解）
─────────────────────────────────────

目的註解應該保持在最小的狀態 --絕不要超過一行。例如：

      : COLD   \ restore system to start condition
          ... ;

另一方面，一個字的目的，經常可藉由它自己的堆疊註解，予以描述出來。你很難會有既需要一個堆疊註解，又需要一個目的註解的情況。例如：

      : SPACES   ( #--)  ... ;

或

      : SPACES   ( #spaces-to-type -- )   ...   ;

這個定義會將堆疊頂端的參數看作是表示需要印出的空格數目。

      : ELEMENT  ( element# -- 'element)   2*   TABLE + ;

這個定義將一個索引值（會被用掉），轉換為一個表格中被它所指著的元素的地址，而這個表格是由2個字元的元素所組成的。

      : PAD  ( -- 'scratch-pad)   HERE  80 + ;

這個定義傳回一個記憶體暫存區的地址。有時，可讀性可以藉著同時記載兩種型式的註解而大為增強。在這種情形下，目的註解應出現在後面。例如：

      : BLOCK  ( n -- a)   \   ensure block n in buffer at a

─────────────────────────────────────
提示不同型式的註解要依一定的順序顯示：輸入字串的註解在最前，堆疊效果的註解其次，目的註解殿後。
─────────────────────────────────────

例如：

      : GET    \ name  ( -- a)   get first match

若有需要，你也可將目的註解寫在第二行：

      : WORD   \ name   ( c -- a)
               \ scan for string deliimt'd by "c"; leave at a
          ...  ;

定義字的註解（Comments for Defining Words）

一個「定義字」的定義牽涉到二種行為（behavior）：

一是當它在定義它的"孩子"時的行為（編譯時區(compiler-time)的行為），以及這個孩子的行為（執行時區(run-time)的行為）。

這二種行為必須分開來註解。

─────────────────────────────────────
提示註解一個定義字的編譯時區的行為時，使用一般的方式；註解它的執行時區的行為時，要跟在『DOES>』或『;CODE』的後面分開來註解。
─────────────────────────────────────

例如：

      : CONSTANT   ( n-- )   CREATE ,
          DOES>   ( -- n)   @ ;

執行時區（孩子）的行為的堆疊效果註解，應該顯示出這個孩子將來在執行時的堆疊的 "淨"效果。因此，它並不包含由『DOES>』所傳回的地址，即使是當這段碼在執行時，這個地址確實地會經由堆疊傳來。

劣（執行時區註解含有apf ）：

      : ARRAY   \ name  ( #cells -- )
         CREATE 2* ALLOT
         DOES>   ( i apf -- 'cell)   SWAP  2* + ;

優：

      : ARRAY   \ name  ( #cells -- )
         CREATE 2* ALLOT
         DOES>   ( i -- 'cell)   SWAP  2* + ;

經由『ARRAY』所定義出的字（它的孩子）都會有下面的堆疊效果：

      ( i -- 'cell)

即使一個定義字並未被指派有「執行時區行為」，這個行為仍然存在，它可以被註解為：

      : VARIABLE  (  name  ( -- )  CREATE  2 ALLOT ;
         \ DOES>  ( -- adr )

編譯字的註解（Comments for Compiling Words）

就如同「定義字」一樣，大多數的「編譯字」也牽涉到兩種行為：

1. 當這個編譯字出現在一個定義中，而這個定義正在被編譯時的行為。 2. 當含有這個編譯字的定義被執行時，這個編譯字的行為。

同樣地，我們也必須對這兩種行為分別做註解。

─────────────────────────────────────
提示註解一個編譯字的執行時區的行為時，使用一般的方式；註解它的編譯時區的行為時，要分開來註解，並在啟始處加上"Compile"（編譯）的標籤。
─────────────────────────────────────

例如：

      : IF   ( ? -- ) ...
      \ Compile:   ( -- address-of-unresolved-branch)
          ... ; IMMEDIATE

在寫編譯字的註解時，第一個註解是用來描述執行時區的行為，通常表示它被"使用"時的"語法"。第二個註解是描述該字在被編譯時，做了些什麼事（這點對使用者是比較不重要的）。

另一個例子：

      : ABORT"   ( ? -- )
      \ Compile:   text"    ( -- )

有時，當一個編譯字在一個冒號定義之外被呼叫時，它可能會表現出不一樣的行為。這類字（是很難伺侯的）需要三個註解。例如：

      : ASCII  ( -- c)
      \ Compile:   c   ( -- )
      \ Interpret:   c   ( -- )
           ... ; IMMEDIATE

本書附錄E中有這類註解的寫法可供參考。

垂直格式對水平格式

註解的目的，在使程式碼的讀者容易看出正在進行的是什麼事。但是，需要多少註解才夠？要決定什麼樣水平的註解才能滿足需要，你必須問自己兩個問題：

誰會來讀我的程式碼？我那些定義的可讀性如何？

註解的文體（styles）基本上有兩種可供選擇。第一種稱為"垂直格式"，其中包含對過程的逐步敘述，就像是做了很好的註解的組合語言程式列表。這種逐步條列的註解稱為"敘事式的註解"。

  \ CRC Checksum
  : ACCUMULATE   ( oldcrc char -- newcrc)
     256 *                   \ shift char to hi-order byte
     XOR                     \ & xor into previous crc
     8 0 DO                  \ then for eight repetitions,
         DUP 0< IF           \ if hi-order bit is "1"
            16386 XOR        \ xor it with mask and
            DUP +            \ shift it left one place
            1+               \ set lo-order bit to "1"
                ELSE         \ otherwise, i.e. hi-order bit is "0"
            DUP +            \ shift it left one place
                THEN
         LOOP ;              \ complete the loop

另一種不在程式碼的片語之間點綴這些敘事式註解的型態稱為"水平格式"。

      : ACCUMULATE   ( oldcrc char -- newcrc)
          256 *  XOR  8 0 DO  DUP 0< IF
            16386 XOR  DUP +  1+  ELSE  DUP +  THEN  LOOP ;

垂直格式適用於一大組程式設計師共同撰寫及維護一個應用程式的情況。一般而言，在這樣的一組人中，有幾個資淺的設計師負責次要的修正工作。在這樣的環境下，費一番心力所做的註解總會節省下大量的時間，並且避免不少的困窘。Moore產業公司的 Johnson說：「當維修程式碼時，你通常只會對其中的一小段有興趣，寫在那兒的資訊越多，儘快修復的機會也就越大。」以下為該公司要求符式程式設計師遵守，且頗合要領的規則。

1. 使用垂直格式。註解寫在原始碼的右方。有需要時，也可以接續到下一行。 2. 註解所用的字數應該比原始碼多。（這個公司鼓勵使用較長的、能充分描述意思的名字） 3. 任何條件結構的字、或應用程式的字，應該分開寫在另一行。"噪音字"可以聚攏在一起。在巢式的條件句中必須使用縮排。（譯註：在符式的核心字中，有些字會妨礙程式的可讀性，如堆疊操作的DUP、DROP等等，它們看來就像是"噪音"）

但是，這種格式也有其若干困難。至少，逐步敘述的註解方式很費時，即使你使用一個相當好用的編輯器也是如此。生產力會受到影響，尤其是當你停下來寫註解而打斷了你的思路時。同時，你也要小心翼翼地確保註解的更新。常有的情形是，程式碼被修改了，修正的版本也經過測試，修正的部份也的確能工作 --但是程式設計師卻忘了去修改註解。註解越多，它們就越有可能是錯的。如果它們是錯的，那可比沒有註解還要糟。如果計劃的負責人能夠費心地檢查以確保註解的正確性，那麼問題還是可以解決的。最後，逐步註解的作法會給人一種虛假的安全感。別以為每行都有一個註解，就表示這個應用程式的註解就是好的。逐步註解並不會指出一個定義運作的精華。例如，所使用的檢查值演算法（checksum algorithm）背後的想法是什麼？誰又能從它的敘事式註解中看出什麼來？要想妥當的描述一個已知程序的糾結過程，通常需要許多段落，而非單一個片語就能成事。這類的描述應該歸屬在補助文件或章節的前言中。撇開這些警告不提，仍有許多公司發現垂直式的註解是必要的。當然，一個剛開始採用符式的工作小組應該要去調適它，就如同任何一個大型的工作小組一樣。水平格式又如何？或許這是個藝術對實際的話題，但是我忍不住要為水平的格式辯護。它同樣地有效，甚至有些方面更傑出。如果符式程式碼寫得到家，就不會有含糊籠統之處。這意思是說：

‧ 支援的詞集有良好設計的語法 ‧ 堆疊的輸入輸出均已註解 ‧ 目的也做了註解（如果從名字或堆疊註解都不能清晰的說明時） ‧ 定義都不太長 ‧ 傳送到單一個定義的堆疊引數都不多（參閱第七章中"合乎體裁的堆疊"）

無論如何，符式與其它語言的確是不同的。逐步註解的作法，不過是用來提高程式可讀性的一些事物之一而已。細膩撰寫的符式程式碼有如詩歌，其所含有的精確意義，是程式設計師和機器二者都容易閱讀的。你的目標應該是：撰寫不需註解的程式碼，即使你決定要為它們做註解。設計你的應用程式時，要讓程式碼 --而非註解-- 表達出你的想法。如果你成功了，那你就擺脫了過度註解的糾纏，臻於言簡意賅，了無瓜葛的境界。

─────────────────────────────────────
提示最精確、最不浪費的說明文件就是能夠自我說明（self-documenting）的原始程式碼。
─────────────────────────────────────

不幸的是，即使最好的程式設計師，一旦遭遇到交卷期限的壓力，也會寫出若沒有註解就難以閱讀的程式碼。若你是寫給自己用的，或是寫給一些"你能用口頭溝通"的人，水平格式是最理想的。否則，你只好考慮垂直格式。

命名的選擇：藝術的部份

除了對數學的嗜好外，若能確實地掌握自己的母語，對一位勝任的程式設計師而言，不啻是萬貫家財。--（Edsger W. Dijkstra教授[3]）

我們曾經討論過，以名字來象徵概念及事物這件事，在應用程式中的重要性。命名已變成設計過程中的重要部份。新進人員總會忽略名字的重要性，他們認為「畢竟，電腦就是電腦，它並不在乎我選用的是什麼名字。」但是問題是，你在乎。好的名字對可讀性是很重要的。甚至於，呼叫一個「單一個字的描述」（one-word description）這種心智上的鍛鍊，能在你的理解力上產生一種連鎖反應，讓你了解那個實體該做什麼，不該做什麼。以下是一些選擇好名字所用的規則：

─────────────────────────────────────
提示命名要根據"做什麼"（what），而非"如何做"（how）。
─────────────────────────────────────

一個定義必須對外面的呼叫者隱藏起它在實現上的複雜度。同樣的，一個名字也必須將程序上的細節隱藏起來，祗表現出其外貌與淨效果來（net effect）。例如，符式字『ALLOT』（配置）僅僅是增加了字典的指標值（在大多數的系統中，指標的名字叫做『DP』或『H』）。但是『ALLOT』這個名字比『DP +!』這個片語好，因為使用者所想要的不過是保留空間，而不是去增加一個指標的值。在1983年的標準中，符式採用『CMOVE>』去代替原來具有同樣功能的『<CMOVE』。這個運作處理了「向前」拷貝到一段重疊的記憶區上的問題。這是經由先移動最高位址的內容，再依序「向後」處理較低的地址，來完成。在新名字中，"做什麼"中的「向前」（以符號 > 來表示）取代了"如何做"中的「向後」（符號 <）。

─────────────────────────────────────
提示要選用那最有詮釋力的字。
─────────────────────────────────────

強而有力的動因在於恰當的字。每當我們從書報中涉獵到非常恰當的字，倏忽之間所感受到的效果，既屬肉體也屬精神，快如閃電。（馬克吐溫）正確的字與那看似正確的字是有區別的，就像天上的閃電和螢火蟲的微光。（馬克吐溫）行顧言；言顧行。（莎士比亞劇作，哈夢雷特第三幕。）

Henry Laxen，一位符式的顧問及作家，認為，符式最重要的一項發展工具應該是一本好辭典[4]。有時候你為一個定義思索一個恰當的名字，但是總令你感覺不妥。幾個月過去了，你才發覺坐失良機。就以第四章中的羅馬數字問題為例，其中有個字是用來處理例外狀況的：也就是處理比下一個符號值少1的那些數字的情況。我第一次是選擇「4-or-9」。那真是難看。但等我想到用「ALMOST」這個名字時，已經過了很久很久了。大多的FIG符式版本的系統，都有『VLIST』這個字。它用來將現行辭彙中的字的名稱列出。好多年以後，終於有人認識到，原來『WORDS』這個字還更為妥當些。它不但唸起來口感好，與那些辭彙名稱合起來用，也更為順暢。例如：

      EDITOR WORDS

或

      ASSEMBLER WORDS

另一方面，Moore也指出，不恰當的名字可以一變而成為防止偷窺的簡單技巧。當你迫不得已，非要公佈你的原始碼時，為了安全，大可以故意地去選擇一些誤導的名稱，使你的程式碼變得非常難讀。當然，修改也就變得不可能了。

─────────────────────────────────────
提示選擇能在片語中表示出意義的那些名字。
─────────────────────────────────────

你面對一個定義，卻不知道該叫它什麼。想想這個字在文句中將如何地被使用。例如：

      SHUTTER OPEN
        對於要用來設定一個名為『SHUTTER』的~BB2;I/O地址中的一個位元而言，『OPEN』是
        個恰當的名字。
      3 BUTTON DOES IGNITION
        『DOES』將『IGNITION』以向量的形式填入某一個功能表（function table）中，
        以便當第三號按扭被按下時，『IGNITION』的功能能得以執行。『DOES』這名字是
        個好選擇。
      SAY HELLO
        『SAY』是個完美的選擇。它以向量的方式將『HELLO』送到一個執行變數中。
        （當我第一次為~BB2;"STARTING FORTH"一書寫出此例時，我稱它為『VERSION』。
         Moore閱讀我的手稿後，建議我用『SAY』。那的確好多了。）
      I'M HARRY
        『I'M』這個字比起常見的『LOGON HARRY』『LOGIN HARRY』或『SESSION HARRY』
         似乎自然得多。

────────────────────────────────
『I'M』的選擇是Moore的另一項發明，他說：

我討厭『LOGON』這個字。英文中沒那種字。我當時正在找一個能表達"I'M.... "句子的一個字。它是個自然的字。我不過是在跨步時碰巧踢到了它。雖然中間那一點不太體面，但它卻給人正確的感覺。所有這些小不點的字都是得到那一聲"阿哈！"反應的康莊大道。如果你盼望的是個正確的字，很顯然地，它就是那個正確的字。如果你所知道的辭彙很充裕，那你就是在一個能夠選擇正確字的較好位子上。
─────────────────────────────────

另一個Moore所喜歡的字是『TH』，那是他用來做陣列索引的字。例如下面的片語

      5 TH

會傳回陣列中第五個（fifth ）元素的地址。

─────────────────────────────────────
提示拼出名字的全名。
─────────────────────────────────────

在一本雜誌上，我曾讀到一份符式程式碼，那位作者似乎是見不得母音字母，例如『DSPL-BFR』，那是"DISPLAY BUFFER"的意思，看起來眼睛發酸。有的作者似乎迷信三個字母就能使盡天下魔術的手法，例如 LENGTH 搖身一變而成 LEN 。這些作法都反映出久遠年代中的一些想法。符式字應該是要完全拼出來的。鍵入 INITIALIZE 或 TERMINAL 或 BUFFER ，心裡要感到驕傲。這些才是你所要表達的。使用縮寫時最糟的事就是，你忘了當初是如何縮寫的，到底是 DSPL 還是 DSPLY ？另一個問題是縮寫有礙可讀性。任何撰寫程式用的語言，就算你不將寫程式的困難算在內，就已經是夠難讀的了。當然還是有些例外，例如：

1. 程式碼中被極度頻繁使用的字。符式中，的確有一小撮最常用到的命令，它們使用幾近於無實質含意的名字：

          :   ;   @   !   .   ,

但這種字少之又少，而卻又那麼頻繁地被使用著，都幾乎變成老朋友了。所以，在正常狀況下，我絕不會鍵入

         DEFINE   END-DEFINITION   FETCH   STORE   PRINT   COMPILE#

（有趣的是，這些符號多半在英文中沒有反義字。我們使用"冒號定義"這種片語，那是因為沒別的術語好用；我們說"逗入一個數值到字典中"（comma a number into the dictionary），那是因為它的確不是在編譯一個數字；況且，也找不到別的術語好用。） 2. 終端機的作業人員經常用來控制作業的那些字。這些字應該以單一個字母呼叫，就如同一些套裝應用程式中所用的"熱鍵"（Hot-key）一般。 3. 某些字，由於大家所熟悉的用法，暗示它們是被縮寫的。符式組譯器的助憶符號就是個典型。它們都符合晶片製造商所建議的助憶符號，而這些都是縮寫的字（例如 JMP 及 MOV 等）。

你所用的名字應該都是可以發音的；不然，等你要和旁人口頭討論程式時，便會後悔不已。如果名稱是個符號，你就該發明出一種拼音法來（例如 >R 要讀"to->"；而 R> 就要讀"r-from"等等）。

─────────────────────────────────────
提示要喜愛短字
─────────────────────────────────────

一個是三音節的字，另一個是單音節的字，兩者若都能表達出相同的意義，你就該選擇那短小者。BRIGHT 比起 INTENSE 來，就是個較好的名字。ENABLE 比 ACTIVATE 好；而 GO，RUN ，或 ON 卻更好。短字鍵入時也方便。它們在原始碼上也節省空間。而最重要的是，它們使你的程式碼清潔而又清脆。

─────────────────────────────────────
提示用連字符號所組成的名字可能意味著不良的分解。
─────────────────────────────────────

───────────────────────────────────────
Moore說：

在符式社團中，程式寫作所用的文體是相當分岐的。某人使用連字符號將許多英文字連為一個字，以表達這個字要做的是什麼。你將一大堆字長長地串接在一起，就得到某種可讀的東西。但我會立刻懷疑，程式設計者是否想過該將這些字打散開來，分別地為每個字下定義。那不是經常都能辦得到的，也不是經常會是有益處的。但我總懷疑，連字符號組成的字是否已將兩種概念攪和在一起。
───────────────────────────────────────

請比較下面同一件事的兩種策略：

      ENABLE-LEFT-MOTOR        LEFT MOTOR ON
      ENABLE-RIGHT-MOTOR       RIGHT MOTOR ON
      DISABLE-LEFT-MOTOR       LEFT MOTOR OFF
      DISABLE-RIGHT-MOTOR      RIGHT MOTOR OFF
      ENABLE-LEFT-SOLENOID     LEFT SOLENOID ON
      ENABLE-RIGHT-SOLENOID    RIGHT SOLENOID ON
      DISABLE-LEFT-SOLENOID    LEFT SOLENOID OFF
      DISABLE-RIGHT-SOLENOID   RIGHT SOLENOID OFF

左列的語法必須用到字典中的8個字；右列語法僅需6個 --而且其中一些字，還很可能會在應用程式的其它部份再被使用到。如果你同時還有一個『MIDDLE』的馬達及電磁閥，你就僅僅需要7個字來描述出16種組合。

─────────────────────────────────────
提示不要把數字捆在名字中
─────────────────────────────────────

小心那些用數字開頭或結尾的名稱，例如 1CHANNEL，2CHANNEL，3CHANNEL等等。像這種名字跟數字捆在一起的情形，很可能是拙劣分解的徵候。其犯的罪過與連字符號相同，祗是這時需要被分解出的是數值而非字。上列名稱的較佳分解作法是

      1 CHANNEL
      2 CHANNEL
      3 CHANNEL

在這種情形下，三個字搖身一變而縮減為一個字。通常，名字與數字相捆就表示含混的命名。在上例中，或許為了要能夠顯示出頻道的目的，而需要使用多個名字來描述。例如

      VOICE , TELEMETRY , GUITAR

我們在下一章"因式分解"中，將對這些概念再予以申論。
命名的標準：科學的部份

─────────────────────────────────────
提示學習並採用符式的命名方式。
─────────────────────────────────────

在尋求短而有意義的名字的過程中，符式程式設計師已經採用了某些命名方法的約定。附錄E中列出了多年來陸續發展出的最有用的約定。這種命名約定的威力可由『.』的使用為例。它表示"印出"或"顯示"的意思。符式本身就使用

      .   D.   U.R

來表示不同型態數值的不同印出格式。這些約定同樣地也適用在應用程式中。如果你有個叫做『DATE』的變數，而你希望有個字來顯示它，就用下面的名字

      .DATE

注意：濫用字頭或字尾會使字醜陋不堪，難以閱讀。不要野心勃勃，想只用一個名字就將那個字的一切作為描述的一清二楚。畢竟，名字只是一個符號，不是程式碼的速食麵。看看下列何者讀來較有口感？

Oedipus complex （伊底帕斯戀母情結 --譯者註）

（它並未帶有生澀的含意），或

subconscious-attachment-to-parent-of-opposite-sex complex

或許是前者吧，即使它假定你已經知道那一齣戲。

─────────────────────────────────────
提示用字頭字尾讓兩個類似的名字判然有別，而不是將雞毛蒜皮硬往名字中塞。
─────────────────────────────────────

例如下面的片語

      ... DONE IF CLOSE THEN ...

和下面的片語一樣的可讀

      ... DONE? IF CLOSE THEN ...

並且同樣的清晰。因此前者就更受歡迎，除非我們需要另一個叫做『DONE』的字（也許作為一個旗標使用）。下面是命名的最後一個提示：

─────────────────────────────────────
提示讓所有16進位數值以數字"0"起頭，以避免和名字相衝突的可能性。
─────────────────────────────────────

例如，寫成 0ADD 這樣，不要寫 ADD。同時，不要指望你的符式系統一定會遵守前述的約定。那些約定是要使用在你的應用程式中的。符式是由一群使用者多年來所創造及淨化而出的，他們將符式看作是抵達終點的一種手段而使用著它。在那段歲月中，要求所有命名的標準都已納入那個正在成長及改變中的工具，是既不合理也不可能的。但是，若符式是經由一個委員會的設計而誕生的（就如其他的電腦語言），我們卻又不會這樣地喜愛她了。
更多的可讀性提示

為了使你的程式碼更具可讀性，這裏還有最後的一些建議。（所有的定義都在附錄C中）在大部份的應用程式中，一個有著極高身價的常數就是『BL』（空格的ASCII值）。『ASCII』這個字主要是使用在冒號定義中，它讓你不必去記住一個字母的ASCII值就能使用它們。例如，你不必寫：

      : (   41 WORD  DROP ;   IMMEDIATE

其中41是右括弧的ASCII值，你可以寫：

      : (   ASCII ) WORD  DROP ;   IMMEDIATE

『TRUE』及『FALSE』這兩個字成雙成對，它們在應付布氏邏輯時，可以增加程式碼的可讀性。有了這些之後，你就能寫出下列的片語

      TRUE 'STAMP? !

去設定一個旗標，或

      FALSE 'STAMP? !

去清除它。（我曾一度使用 T 及 F ，但是因為這些字用到的機會極為有限，我現在轉而注意到縮寫的禁忌上。）作為應用程式的一部份（倒不一定是你的符式系統的一部份），你可以帶著此一概念向前再多跨一步，並做出下面的定義：

      : ON  ( a--)   TRUE SWAP ! ;
      : OFF  ( a--)   FALSE SWAP ! ;

這些字容許你寫出：

      'STAMP? ON

或

      'STAMP? OFF

其它用在這些定義上的名字包括 SET 及 RESET ，雖然 SET 及 RESET 大多數是用在位元遮罩（bit mask）的運作上，用來處理個別的位元。另一個常用的字是『WITHIN』，它決定某個值是否在另外兩個值之間。其語法為：

      n  lo hi WITHIN

其中，n 是受測值，lo 及 hi 表示範圍。若 n 大於或等於 lo，且小於 hi 時，『WITHIN』會傳回一個真。這種不含上限的做法是為了與『DO LOOP』的語法相當。 Moore推薦『UNDER+』這個字。若要加一個值到堆疊頂端的下一個參數上，它會很管用。用高階定義來實現時就是：

      : UNDER+   ( a b c -- a+c b )   ROT +  SWAP ;

結語：

程式的可維修性需要可讀性的幫助。本章列舉了許多途徑，以使原始碼變得更為可讀。我們也曾自我期許，要使程式碼儘可能地做到自我說明。其中的技巧包括程式列表的組織、間隔及縮排、註解、命名、以及可以增進清晰度的特別符號。我們祗簡單地提到了關於輔助性文件，那是指除了程式列表之外的其它東西。本書將不再進一步的討論這些，但它們仍然是完整軟體發展過程中不可或缺的一部份。
　

參考資料

1. Gregory Stevenson, "Documentation Priorities," 1981 FORMAL Conference Proceedings, p. 401. 2. Joanne Lee, "Quality Assurance in a FORTH Enviroment," (Appendix A,) 1981 FORMAL Proceedings, p. 363. 3. Edsger W. Dijkstra, Selected Writings on Computing: A Personal Perspective, New York, Springer Verlag, Inc., 1982. 4. Henry Laxen, "Choosing Names," FORTH Dimensions, Vol. 4, No. 4, FORTH Interest Group.

第五章 實現階段：符式文體的組成元素 （Elements of Forth Style）

第五章實現階段：符式文體的組成元素（Elements of Forth Style）