加速代碼文檔的編制的幾個有效思路

2019-11-18 12:03:55

字體：大中小

來源：轉載

供稿：網友

　　眾所周知，文檔編制在軟件項目中是一個至關重要的部分。它貫穿整個項目并應該得到足夠的維護。不幸地是，一個文檔的編制很復雜，需要耗費大量的時間，所以它成為了軟件開發人員的負擔，這樣就使文檔編制變得不完整并且不能和程序同步修改。源代碼文檔編制是整個代碼進程中一個重要的一部分，在這個進程中，需要利用到javadoc工具。利用一個簡單的文本編輯器和一個正確的項目目錄結構，這個工具可以幫助你加速和改善代碼文檔編制。
　　
　　項目目錄結構
　　一個正常的軟件項目有一系列的文檔，比如需求，規格說明，測試和一個和系統開發人員工作有關的集成計劃。讓我們來看看一個適合開發項目的典型的目錄結構：
　　
　　　/PRj-1
　　　　　 /classes
　　　　　 /doc
　　　　　 /resources
　　　　　 /spec
　　　　　 /src
　　　　　 spec.Html
　　
　　/class目錄存儲編譯Java類文件，/dos有文檔編制，/resources是項目資源，/spec是項目文檔編制，/src是Java源文件。Spec.html是一個映射文件，我將在后面討論它。
　　
　　或者，這個目錄結構可以象下面這樣編寫，此時，和項目相關的文檔編制被放置在比源代碼更高一級的地方。
　　
　　　　/prj-2
　　/code
　　/classes
　　/doc
　　/resources
　　/src
　　spec.html
　　　　　 /spec
　　
　　這種結構的好處就是它很輕易的被封裝，因而可以從/src目錄中設置地址，源文件被存放在這個目錄中，這兩個結構都可以正常的工作。在這篇文章下面的例子中，我們使用第一種目錄結構。
　　
　　使用目錄結構
　　假設你已經完成了一個算法，這個算法在規格說明中進行了徹底地解釋，現在你想要文檔編制這個代碼。你可以提供一個連接，使它連接說明的原始地方，這樣就替代了重復的解釋算法。這樣就使代碼編制變得更快，它不需要復寫原始信息并可以同步的保持代碼內容。
　　
　　源文件和項目文檔的連接被放置在/spec目錄中，你需要利用HTML和Javadoc來創建這個連接。連接可以指向存儲于不同格式的文檔，這些格式可以通過你的瀏覽器被瀏覽。
　　
　　/**
　　*　Process a customer order according to the
　　*　<a href="../spec/specification.html#cust-order-proc">specification</a> and
　　*　<a href="../spec/requirements.rtf">requirements</a>
　　*/
　　public void processCustomerOrder() {
　　...
　　}
　　/**
　　*　Creates and sends
　　*　<a href="../spec/specification.html#cust-order-diag-resp">
　　*　a response message</a> according to
　　*　<a href="../spec/specification.html#cust-order-diag">a customer request</a>
　　*/
　　public void generateCustomerResponse() {
　　　
　　}
　　
　　假如文檔編制和源代碼一起都是分布式的，那么使用這個方法是非常有效的。但是，假如這樣做，源代碼的注釋將要加上一個非凡的文檔編制名和它的位置，改變它們中任何一個其他的也要改變。
　　
　　為了糾正這個確定，你僅僅需要在源代碼和非凡文檔中的連接提供一個映射，這個過程通過映射文件可以非常簡單的完成。比如，spec.html包含了在源代碼中連接用戶名和文檔中實際名之間的映射。你可以看看下面這個例子：
　　
　　/**
　　*　Performs a complex calculation according to the
　　*　<a href="../spec.html#algorithm-1">algorithm</a>
　　*/
　　public void doComplexCalculation() {
　　
　　…
　　
　　 spec.html文件包含了下面的映射：
　　
　　<a name="algorithm-1">
　　　 <a href="spec/algorithms.html#1">Algorithm 1</a>
　　</a>
　　</p>
　　<p>
　　<a name="ant-ref">
　　　 <a >Apache Ant Java-based build tool</a>
　　</a>
　　</p>
　　<p>
　　<a name="common-properties">
　　　 <a href="resources/prj-1.properties">Common Properties</a>
　　
　　連接程序表
　　　　我們來看看另外一個例子，你需要一個地方來連接外部文檔到你的源代碼中，你想要的位置在更高級別設計文檔，包括使用范例或者程序表。當你想要指定系統通信，交互作用或者和其他系統接口的時候，程序表是非常有用的。不幸地的是，你不能自動的在程序表中產生代碼，也不能在程序表中重新設計源代碼。因此，你需要同時保持程序表和源代碼。假如你連接了一個程序表，這個過程就變得簡單多了。比如，在這兩個參與者中傳遞消息。假設你的程序表是簡單的ASCII程序表，你可以按下面的步驟創建anchor：
　　
　　Customer　　　　　　　　　　　　　　　　　　　　 Processor
　　　 --------　　　　　　　　　　　　　　　　　　　　　---------
　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　
　　　　　 OrderRequest　　　　　　　　　　　　　　　　　　　　　　　　　　
　　　　　------------------------------------------------->　　　　　　
　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　
　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　
　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　
　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　
　　　　　 <a name="cust-order-diag-resp">OrderResponse</a>　
　　　　　<-------------------------------------------------　　　　　　
　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　
　　
　　接著，通過spce.html連接映射文件。
　　
　　象上面這種方式安排文檔編制的進程是比較簡單，合理的。因為它僅僅需要一個文本編輯器和Javadoc工具。

上一篇：開發基于JNDI的應用程序

下一篇：想要開始為 Java 手機開發應用程序嗎？