10個專案文件最佳實踐

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

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

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

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

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

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

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

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

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

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

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

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

　　英文原文：10 Software Documentation Best Practices