10 個專案文件最佳實踐

jieforest發表於2012-11-22
在軟體開發和維護過程中,文件是必不可少的資料,它可以提高軟體開發的效率,保證軟體的質量,而且在軟體的使用過程中有指導、幫助、解惑的作用。尤其在維護工作中,文件的重要性更是不言而喻。

本文整理了軟體開發中10個最佳的文件編寫實踐,希望能對你的工作有所幫助。

1.  將編寫文件作為開發工作中的一個重要環節(例如,佔用總開發時間的10%)。在軟體開發中,不能沒有文件,但如果編寫文件佔用了大部分的時間也不合適。可以根據需要制定程式碼文件、需求說明文件、設計文件、測試文件、使用者手冊等,在制定完成後,可以通過版本控制工具或基於Web的平臺來管理和共享這些文件。

2.  程式碼文件非常重要的。最好的方式是編寫“自說明”的程式碼,變數、方法、類、包等名稱必須是有意義的,程式碼流必須是清晰的。對於非常複雜的程式碼段,可以包含簡短的註釋行。還可以在程式碼中新增相關的標籤或註釋,自動生成Javadoc文件。

3.  對於將來接手的開發者,可以為他們準備一些簡短、實用的設計文件,其中需要包含關鍵設計特性和UML圖等,無需出現大量不必要的資訊。

4.  需求/問題/未交付專案/功能點跟蹤文件也相當重要。使用跟蹤工具將會使這項工作更加有效率,這些工具可以幫助你完成一些像快速搜尋、編輯等方面工作,並可以生成純文字文件。

5.  測試跟蹤文件也很重要。可以使用一些工具來記錄測試場景和測試結果,並附上一些相關的需求。這樣,可以很容易地監視軟體的功能狀態。

6.  文件是一個持續性的工作,開發人員應該隨時更新或重新生成這些文件的最新版本,直到開發程式結束。如果一個文件不是最新的,那麼它毫無價值。

7.  對於文字形式的文件,版本相當重要。每一個新的文件,必須有一個新的版本號(版本號由公司的版本管理策略來定),還需要將這些資訊記錄在版本跟蹤表中,以便更好地跟蹤。

8.  有一個統一的文件模板。文件的頁首、頁尾、標題、字型大小必須一致,這樣可以增強可讀性。還可以做得更好,比如加上封面、目錄、圖表、詞彙表等。

9.  還需要注意文件格式、使用的語言、錯別字等。輸入錯誤、不一致的表格大小、縮排等問題,可能會分散閱讀者的注意力。

10.  將專案中學到的經驗記錄下來,並分享給其他人。開發者在每個專案中都可能會得到一些實用的經驗(比如架構、程式碼、配置等),而這些經驗資訊不會出現在標準的開發文件中。開發者要不斷積累並分享這些經驗,這可能會加快當前的開發進度,而且對於將來做一些有挑戰的工作或者重複性的工作,會有很大的幫助。

來自 “ ITPUB部落格 ” ,連結:http://blog.itpub.net/301743/viewspace-749732/,如需轉載,請註明出處,否則將追究法律責任。

相關文章