從文檔規範性中想到的

       軟體開發人員不隻是要寫程式，還要編寫各式各樣的文檔。有的時候，花在寫文檔上的時間甚至還比花在寫程式上的時間還要多一些。很多開發人員認為文檔編寫不重要，于是敷衍了事，讓之後閱讀文檔的人看得是雲裡霧裡，極大地影響了工作的效率。

       最近，我看了兩個不同軟體版本中的內建測試文檔，頗有感觸。

       內建測試文檔1的結構是這樣的：

1. 引言

2. 術語、定義和縮略語

3. 內建目标

4. 內建任務

  4.1 內建任務1

  ……

  表1

  ……

  圖1

  ……

  4.2 內建任務2

  ……

  表2

  ……

  圖2

  ……

   4.3 內建任務3

  ……

  表3

  ……

   圖3

  ……

  ……

5. 內建工具及環境說明

6. 附件

7. 參考文獻

      內建測試文檔2的結構是這樣的：

1. 引言

2. 術語、定義和縮略語

3. 內建目标

4. 內建任務

  4.1 內建任務1

  ……

  表4.1.1

  ……

  圖4.1.1

  ……

  4.2 內建任務2

  ……

  表4.2.1

  ……

  圖4.2.1

  ……

   4.3 內建任務3

  ……

  表4.3.1

  ……

   圖4.3.1

  ……

  ……

5. 內建工具及環境說明

6. 附件

7. 參考文獻

       大家可能已經看出來了，這兩份文檔隻是在紅色字型部分有差別，其它部分都是一樣的。在內建測試文檔1中，圖表的編号采用了“圖1、圖2、圖3、表1、表2、表3”的形式；在內建測試文檔2中，圖表的編号采用了“圖4.1.1、圖4.2.1、圖4.3.1、表4.1.1、表4.2.1、表4.3.1”的形式。大家也許覺得這個差别沒什麼，就是一個編号的方案不同而已。

        确實，從表面上看隻是編号方案不同，但在軟體版本不停演進的過程中，差别就展現出來了。為什麼呢？請容我慢慢道來。

4. 內建任務”這一節中完成的。也就是說，第4節的内容在不斷地添加，也許會從“4.1”發展到“4.20”乃至“4.100”，并且這些添加可能是由不同的開發人員完成的。

        當第4節的内容足夠多時，兩份文檔表現出來下面的不同：

圖6、圖6、圖6、圖7……表1、表2、表3、表3、表4、表5、表6、表7、表7、表7……”。很明顯，這是很不規範的，影響了對文檔的閱讀。

        (2)對于內建測試文檔2，即使發展到很高的版本，也不會有問題，如“4.10”節，圖表的編号就是：“圖4.10.1、圖4.10.2、圖4.10.3…表4.10.1、表4.10.2、表4.10.3…”。因為圖表的編号隻與所在的節有關，不需要與前後節有任何關聯，是以能夠保證其正确性。

        圖表的編号雖然是一個很小的問題，但我們卻可以從中看出軟體的不同設計方案所帶來的不同結果。具體而言，我個人認為：

        (1)軟體産品的設計方案一定要考慮到未來的發展，即可擴充性，要為以後的版本打下一個好的基礎。內建測試文檔2在這方面就做得比較好，而內建測試文檔1沒有考慮到未來在編号上出錯的可能，這種方案就設計得不合理。

        (2)軟體産品的設計一定要遵循“高内聚、低耦合”的設計理念，即要減少一個子產品與其它子產品在資料、消息等上面的關聯，而應該增強子產品内部的關聯性。內建測試文檔1中某節圖表的編号與前面節圖表的編号的關聯性很強，而內建測試文檔2各節圖表編号沒有任何關聯。是以，在圖表編号上的設計，內建測試文檔1比內建測試文檔2遜色很多。

       (3)軟體産品的設計一定要展現出專業性。在這點上，“圖1、圖2、圖3、表1、表2、表3”肯定沒有“圖4.1.1、圖4.2.1、圖4.3.1、表4.1.1、表4.2.1、表4.3.1”看起來專業。是以，從專業性的角度看，內建測試文檔1也要比內建測試文檔2差。