SVN 軟件開發日誌規範
前言：寫代碼的好習慣除了言簡意賅的註釋外，還有完善且必要的日誌。註釋主要是對代碼內的模塊或功能函數、算法、邏輯框架等進行必要簡明的說明，它關注的是”這個“代碼裏做了什麼。而日誌需要說明的是這版代碼和上一版本改了什麼（重點關注代碼的升級迭代、用途、風險），和其他代碼有啥關係（比如關注是否某些功能模塊借鑑或移植於其他項目）。所以日誌主要關注的是“這些”代碼之間的關係（改動、移植），以及怎麼用它，有何風險。所以不要覺得代碼裏寫了足夠的註釋就不需要寫Log了，經驗豐富的軟件開發們會形成自己完整的一套規範風格。
如何寫代碼日誌？
這是我們要回答的第一個問題。通過上面的簡介我們大致知道代碼Log需要記錄哪些信息了，但是這還不夠。做軟件一個很重要的思維方式就是把問題分類或分塊進行細化。一版代碼按照開發的進程分，可以分爲首次開發和變更開發。按照軟件發佈的用途分，可以分爲臨時程序（用於新方案實驗、輔助硬件測試、給客戶送樣等）和受控程序（指正式出貨的程序）。按照發布次數可以分爲初版發佈和變更發佈（程序升級）。另外還可以根據自己特色進行分類，比如按所用芯片型號、平臺、開發語言、內部開發或內外合作。你的日誌裏要能清晰分辨出來現在在做的是屬於哪一類程序。
先弄清楚現在要寫的是什麼程序
當項目立項時,我們第一步當然是仔細閱讀相關文檔（可能是設計開發要求、方案策略設計說明、設計變更通知單、產品立項報告等等，不同的公司會有較大的差異，當然有些公司沒有任何文檔，全靠嘴（我這經歷過什麼。。。））。這些文檔裏除了告訴我們需要做出什麼樣功能的程序外，我們還能知道這是一個新項目還是老項目升級，這是將來要正式出貨的程序還是隻是實驗程序。如果是老項目程序升級，那它就一定存在歷史版本，且應該清楚的知道改動了什麼。如果是正式出貨的程序，那它一定有適用範圍，比如這版程序用於哪些型號，哪些芯片或平臺，甚至應該有對應的硬件版本號（當然，當硬件電路做出改動時軟件需要評估是否能兼容，這種問題比較多發生在嵌入式行業，互聯網行業就是所用的架構和平臺版本了）。如果是臨時程序，一定要把它區別於正式程序，寫明程序的意圖和提供給了誰，特別是做了某些實驗驗證後會得出一些進展結果，能說明的儘量說明。
開發一版程序往往不可能SVN只上傳一次就成功，開發過程中，每天下班前上傳新代碼並寫上Log是一個好習慣，這種情況需要簡明的寫上代碼改動點和遺留問題，方便下一次開發能快速銜接。
未發佈軟件Log模板
--------------------------------代碼開發----------------------------------------------
工程名：（寫這個並不重複，因爲工程名後期可能會改（雖然幾乎不會），每個日誌都寫方便追溯。）
軟件版本：（如：200305 V1.0）
上傳修改：（首次上傳/修改上傳。）
版本迭代：（初版/在某某版本上變更升級。）
上傳人：（還是建議給自己取個英文名吧。）
上傳時間：（比如用六位日期數字200303，別想了，下個世紀你的程序早被淘汰了。）
上傳原因：（如果是首次上傳就寫明開發目的，如：某某項目生產出貨、用於某實驗、給某客戶送樣等，如果是開發過程中的修改上傳就寫開發上傳。）
修改點：（這個很重要，要做到描述簡明但不漏點，就是說改動了哪幾個大方向要一個不漏，但是這些方向細節改了什麼這裏只用簡明概括，想了解細節的時候對比代碼就行了，當然代碼內註釋要寫好。）
遺留問題：（如果是在開發過程中的修改上傳，寫明還未進行和還未完成的功能，以便下次繼續開發。如果是已經發布的程序，寫明軟件的風險點，方便未來軟件升級時優化或排查Bug時更快定位問題。如果暫未發現風險點則寫未知。）
適用範圍：（在這裏寫明用於什麼芯片或平臺。用了什麼開發工具（有些大公司比較統一，而且萬年不升級工具，一般小公司比較亂，不同的人用不同版本的IDE，甚至不同的開發語言。適用於哪些項目，寫上項目名。總之限制軟件通用性的條件可以寫在這裏。）
* 使用芯片：
* 硬件版本：
* 適用項目：
* 適用協議：
工具平臺：（在這裏寫上所用開發工具或平臺的版本。）
* 底層庫版本：
* 編譯器：
* 離線編程器上位機：
其他描述：（需要提示或強調的東西，比如和某第三方公司合作開發，分別負責什麼模塊之類的。）
軟件發佈時應該寫什麼Log
像前面的開發日誌主要是寫給軟件開發人員看的，而發佈出去的程序供給外部門，他們不需要知道太多軟件修改的細節，主要需描述清楚3點：1、這版軟件實現了哪些功能。2、適用範圍。3、風險點有哪些。發佈日誌還有一個重要的信息，就是版本的升級迭代關係。這版軟件是用於替換哪版舊軟件，還是初版軟件，這一點也可以歸類到適用範圍裏。一些大公司有完善的流程管理平臺（比如JIRA等），相關的信息詳細記錄在平臺上。對於一些未搭建平臺的小公司建議在工程裏創建一個文檔，隨着開發過程保持文檔更新。這份文檔在最終出貨時可以做成軟件適用說明文檔給出去。
已發佈軟件Log模板
--------------------------------軟件發佈----------------------------------------------
發佈軟件名：（要發佈的是軟件名稱，名稱裏要帶上軟件版本號。）
軟件版本：（如：200305 V1.0）
項目當前狀態：（完成/進行/暫停/廢止）
發佈目的：（用於某項目產品生產出貨/用於某項實驗/）
版本特徵：（正式出貨的爲Release版，其他爲Debug版。）
版本迭代：（初版/在某某版上修改）
發佈人：
發佈時間：
功能描述：（列舉出該版軟件已經實現的功能，重點描述設計開發要求上提到的功能的實現情況。只寫實現了沒有，不要在這裏囉嗦描述爲什麼沒有實現原因等。）
變更原因：（如果是舊版基礎上變更則寫明變更原因。若爲初版則寫初版即可。）
變更點：（變更程序簡明寫變更點（這裏不要寫詳細的軟件修改點，從前後兩版的功能角度寫解決了什麼Bug或做了什麼優化。若爲初版則寫初版即可。）
適用範圍：（在這裏寫明用於什麼芯片或平臺。用了什麼開發工具（有些大公司比較統一，而且萬年不升級工具，一般小公司比較亂，不同的人用不同版本的IDE，甚至不同的開發語言。適用於哪些項目，寫上項目名。總之限制軟件通用性的條件可以寫在這裏。）
* 使用芯片：
* 硬件版本：
* 適用項目：
* 適用協議：
測試情況：（通過測試/未通過測試）
遺留問題：（寫明風險點，如果暫未發現風險點則寫未知。）
工具平臺：（在這裏寫上所用開發工具或平臺的版本。）
* 底層庫版本：
* 編譯器：
* 離線編程器上位機：
其他描述：（需要提示或強調的東西，比如和某第三方公司合作開發，分別負責什麼模塊之類的。）
如何寫文檔日誌？
上面已經討論過如何給代碼寫上日誌，在開發過程中一個軟件開發人員會接收和產出很多文檔，這些文檔都需要和項目相關聯並並在SVN等平臺做好記錄並上傳，也會設計到Log的編寫。一般來說文檔的Log相對顯得不那麼重要，只需在日誌裏說明上傳的文檔裏包含了哪些信息，屬於哪個項目，文檔修改時簡略說明文檔的修改點。當然比較重要的信息比如調試測試報告測出Bug或發現風險時，也請在Log裏簡明描述下。有些公司會按照文檔的類別進行分類Log，比如調試測試報告的Log規範和軟件其他文檔Log規範不同，這裏我只介紹通用簡單的模板。
文檔Log模板
--------------------------------文檔上傳----------------------------------------------
上傳修改：（首次上傳/修改上傳。）
上傳人：
上傳時間：
上傳原因：（比如：某某項目某版軟件設計開發要求。某某項目某版軟件調試報告。流程規範化軟件則寫軟件規範化實施說明管理文檔。等等。）
修改點：（簡明寫文檔做了哪些改動，如果第一次上傳就寫首次上傳。）
其他描述：（需要提示或強調的東西，比如調試測試報告裏發現的Bug或風險點。）
實際這個規範不僅可用於SVN規範也能套用到其他平臺和部門