|
加速代碼文檔的編制的幾個(gè)有效思路時(shí)間:2004-07-14 08:00來(lái)源:中國(guó)網(wǎng)管聯(lián)盟 bitsCN編輯字體:[大 中 小]
眾所周知，文檔編制在軟件項(xiàng)目中是一個(gè)至關(guān)重要的部分。它貫穿整個(gè)項(xiàng)目并應(yīng)該得到足夠的維護(hù)。不幸地是，一個(gè)文檔的編制很復(fù)雜，需要耗費(fèi)大量的時(shí)間，所以它成為了軟件開發(fā)人員的負(fù)擔(dān)，這樣就使文檔編制變得不完整并且不能和程序同步修改。源代碼文檔編制是整個(gè)代碼進(jìn)程中一個(gè)重要的一部分，在這個(gè)進(jìn)程中，需要利用到j(luò)avadoc工具。利用一個(gè)簡(jiǎn)單的文本編輯器和一個(gè)正確的項(xiàng)目目錄結(jié)構(gòu)，這個(gè)工具可以幫助你加速和改善代碼文檔編制。 項(xiàng)目目錄結(jié)構(gòu) 一個(gè)正常的軟件項(xiàng)目有一系列的文檔，比如需求，規(guī)格說(shuō)明，測(cè)試和一個(gè)和系統(tǒng)開發(fā)人員工作有關(guān)的集成計(jì)劃。讓我們來(lái)看看一個(gè)適合開發(fā)項(xiàng)目的典型的目錄結(jié)構(gòu)： /prj-1 /classes /doc /resources /spec /src spec.html /class目錄存儲(chǔ)編譯Java類文件，/dos有文檔編制，/resources是項(xiàng)目資源，/spec是項(xiàng)目文檔編制，/src是Java源文件。Spec.html是一個(gè)映射文件，我將在后面討論它。 或者，這個(gè)目錄結(jié)構(gòu)可以象下面這樣編寫，此時(shí)，和項(xiàng)目相關(guān)的文檔編制被放置在比源代碼更高一級(jí)的地方。 /prj-2 /code /classes /doc /resources /src spec.html /spec 這種結(jié)構(gòu)的好處就是它很容易的被封裝，因而可以從/src目錄中設(shè)置地址，源文件被存放在這個(gè)目錄中，這兩個(gè)結(jié)構(gòu)都可以正常的工作。在這篇文章下面的例子中，我們使用第一種目錄結(jié)構(gòu)。 使用目錄結(jié)構(gòu) 假設(shè)你已經(jīng)完成了一個(gè)算法，這個(gè)算法在規(guī)格說(shuō)明中進(jìn)行了徹底地解釋，現(xiàn)在你想要文檔編制這個(gè)代碼。你可以提供一個(gè)連接，使它連接說(shuō)明的原始地方，這樣就替代了重復(fù)的解釋算法。這樣就使代碼編制變得更快，它不需要復(fù)寫原始信息并可以同步的保持代碼內(nèi)容。 源文件和項(xiàng)目文檔的連接被放置在/spec目錄中，你需要利用HTML和Javadoc來(lái)創(chuàng)建這個(gè)連接。連接可以指向存儲(chǔ)于不同格式的文檔，這些格式可以通過(guò)你的瀏覽器被瀏覽。 /** * 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() { } 如果文檔編制和源代碼一起都是分布式的，那么使用這個(gè)方法是非常有效的。但是，如果這樣做，源代碼的注釋將要加上一個(gè)特別的文檔編制名和它的位置，改變它們中任何一個(gè)其他的也要改變。 為了糾正這個(gè)確定，你僅僅需要在源代碼和特殊文檔中的連接提供一個(gè)映射，這個(gè)過(guò)程通過(guò)映射文件可以非常簡(jiǎn)單的完成。比如，spec.html包含了在源代碼中連接用戶名和文檔中實(shí)際名之間的映射。你可以看看下面這個(gè)例子： /** * 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 href="http://ant.">Apache Ant Java-based build tool</a> </a> </p> <p> <a name="common-properties"> <a href="resources/prj-1.properties">Common Properties</a> 連接程序表 我們來(lái)看看另外一個(gè)例子，你需要一個(gè)地方來(lái)連接外部文檔到你的源代碼中，你想要的位置在更高級(jí)別設(shè)計(jì)文檔，包括使用范例或者程序表。當(dāng)你想要指定系統(tǒng)通信，交互作用或者和其他系統(tǒng)接口的時(shí)候，程序表是非常有用的。不幸地的是，你不能自動(dòng)的在程序表中產(chǎn)生代碼，也不能在程序表中重新設(shè)計(jì)源代碼。因此，你需要同時(shí)保持程序表和源代碼。如果你連接了一個(gè)程序表，這個(gè)過(guò)程就變得簡(jiǎn)單多了。比如，在這兩個(gè)參與者中傳遞消息。假設(shè)你的程序表是簡(jiǎn)單的ASCII程序表，你可以按下面的步驟創(chuàng)建anchor： Customer Processor -------- --------- | | | OrderRequest | |-------------------------------------------------> | | | | | | | | | | <a name="cust-order-diag-resp">OrderResponse</a> | |<------------------------------------------------- | | | 接著，通過(guò)spce.html連接映射文件。 象上面這種方式安排文檔編制的進(jìn)程是比較簡(jiǎn)單，合理的。因?yàn)樗鼉H僅需要一個(gè)文本編輯器和Javadoc工具。 【轉(zhuǎn)自www.bitsCN.com】 |
|
|
