文檔代碼同源

目錄

1、問題起源

2、解決方案

2.1、需求和代碼對應

2.2、每日檢查

2.3、飛行檢查

2.4、公共模塊

3、補充說明

4、遺留問題

文檔代碼同源，故名思意，就是文檔和代碼都寫在源代碼文件里。這樣可以：1.修改代碼的時候就及時修改文檔，使得文檔和代碼及時保持一致；2.閱讀代碼時，增加代碼的可讀性。評審代碼的時候，尤其是修改時后，即對文檔一同評審。結合研發流程、評審的配合，可促使代碼、文檔的開發逐步走向一一對應，逐步向高質量發展，同時也能提高團隊素質。

1、問題起源

互聯網行業和一些物聯網行業，軟件開發都提倡敏捷開發，敏捷開發為何物？(附件介紹。)這里列出敏捷的宣言：

個體和互動高于流程和工具

工作的軟件高于詳盡的文檔

客戶合作高于合同談判

響應變化高于遵循計劃

也就是說，盡管右項有其價值，

我們更重視左項的價值

很多公司所謂的敏捷，很大程度上就是開發代碼，應該有的必要文檔可能都是不全的。因為要趕工，因為市場的巨大壓力，文檔代碼對應不上司空見慣。更有甚者，壓根就沒有文檔。這里造成了很多隱性的問題。

1.沒有合適的文檔，隨著時間的推移，一些技術要點，設計要求，設計思路隨著時間，盡歸塵土。這些通過市場、技術、商業等各個維度試錯的來的寶貴經驗和知識無法傳承，是一種浪費，更是一種低效組織的表現。

2.關鍵崗位的開發人員一旦流失，產生的技術、知識斷崖，短期內難以補足。

3.新人的進入，需要長時間的消化理解。

4.代碼的評審和檢查不嚴格，想怎樣改就怎樣改，只要外在的功能是正常的。那就是沒有問題的。為很多問題埋下了伏筆和隱患。

敏捷中有一個觀點，竊以為是無比正確的：沒有什么文檔比代碼更準確。但這個觀點又是比較危險的：

1.可運行的功能正確的代碼的確是沒有什么比其更準確的了。但是，代碼畢竟是寫給機器運行的，個人的能力、習慣等都不一致，其他人理解起來必然費勁。有一些飽含技巧的寫法可能是需求的需要，也可能是個人炫技的需要；其他人又怎能看透全部呢？代碼畢竟是非自然語言，有時候能看得懂代碼，是以犧牲速度為代價的，總之，問題比較多。

2.潛臺詞是，文檔不重要。

總之，文檔、代碼的問題，不僅困擾著程序員，也困擾著公司。那么怎么找一個合適的方法解決這個問題呢？

2、解決方案

想想程序員為什么寫或修改代碼？我想即使是為了拯救地球和全宇宙，從微觀上講，也符合下列情況之一：

1.實現需求。是的，這怕是程序員寫/修改代碼的第一大原因了。

2.抓Bug。程序員實現需求的副產品：八阿哥(bug)。把它送走，是我們改代碼的第二大驅動。

3.其他原因，諸如設計不足，可理解性不好啦，模塊用起來不爽啦，封裝不夠簡潔實用，有一些程序員還有潔癖。這可能都是修改代碼的原因。但從本質上來講，也是滿足需求的修改。每個產品需求定義之外，都有灰色邊界。需求提得越清楚，灰色地帶就越少。閱讀性不好、模塊用起來不爽，可能在需求里沒有提出來。有些作為需求提出來，也是可以的。比如說，對于產品某個模塊的要求，必須使用什么標準技術或模塊，或者必須滿足下一代的復用等。至于潔癖，團隊沒有定義團隊的寫法，那么沖突修改是必然的。

代碼中所有的修改都可歸為這三類，更進一步，大部分應該是前兩類。開源世界有一個很好用的工具是Doxygen。它的作用就是把代碼里的特殊注釋抽取出來變為文檔(一個類似Latex的工具，非所見即所得的文檔編輯工具)。我們的思路就是，利用Doxygen工具，將代碼和文檔的開發變為同步過程。由于文檔含在代碼里，也意味著Doxygen的文檔也是文本，在版本庫的管理下，能精確的看到每一個比特的修改。(后面有文章做一個的Doxygen介紹。)這里簡單的介紹一下Doxygen。

Doxygen?是一個程序的文檔產生工具，可將程序中的特定注釋轉換成為說明文件。比如說對于以下這段注釋：

以上經過Doxygen抽取編譯后，會生成一個綜合性文檔，可在里面查到：

即使我們不用doxygen編譯，寫在代碼里的注釋，也是不影響我們理解的。只是編譯后，查閱起來更方便。

這是我們實現文檔代碼同源的基礎。但文檔代碼的同源不僅僅是把代碼和文檔合成一個源代碼文件。我們要做得是：

1.需求要和代碼中的各個實現模塊對應起來；

2.文檔的修改、代碼的修改同步進行，每天由工程師交叉檢查并給出評語；

3.高級技術人員定期整理代碼問題，形成案例；

4.如果是公共模塊，項目進行過程中，定期整理其Bug，問題，維護其可用性。

2.1、需求和代碼對應

開發一款產品，首先要提需求，需求開發出來，大抵是這樣的：

需求提出了方方面面的要求，一般，需求的分配表也跟在后面，用于指示這個需求都由那些模塊實現。

緊接著下來是軟硬件的概要或者詳細設計，有些公司為了節省，就只有設計；有的干脆就連設計也省了，走“敏捷"路線。這個并不重要。

Doxygen支持自由頁面，可以寫一個Python的小工具，將excel的需求表轉化為?txt的文本文件，被doxygen所識別。

這樣做得好處：

1.需求只要經常用版本庫追蹤，誰改了一個字，改了什么都會清清楚楚。

2.程序員查閱需求會更加簡便。同時，每日的檢查強調，需求的修改，可能會帶來代碼的修改；Bug的修改可能帶來代碼的修改，需求的修改。從而強調需求的定義作用，主動維護需求的前后一致。

如模塊中編寫時，說明實現了哪些需求。

這些都是超文本標簽，點擊后迅速轉到需求定義處可查看。

2.2、每日檢查

該方法的核心內容，就是每日檢查。一個程序員每天的代碼產量最多可達上千行(非每日平均產量)。如果是更改Bug，可能一天大部分的時間用于分析跟蹤上。正真的修改并不多。每日提交版本庫后，由其他程序員或者部門經理檢查代碼及修改，檢查的內容如下：

1.代碼修改是否有效，符合組織內部的規定；

2.文檔和代碼是否對應。

與需求類似，寫一個Excel表格，包含：模塊；檢查人；日期；問題描述的跟蹤表；檢查完成后提交至版本庫，由對應的工程師承接修改。

每次檢查，檢查文檔、代碼的問題，通過版本庫可以很輕松的跟蹤相關的修改。并定位修改是否合理。

2.3、飛行檢查

為了防止檢查流于形式，定期對一些具有代表性的問題做總結。高級技術人員需要做一些飛行檢查，定期的抽查檢查表以及文檔代碼的對應情況。并從問題中選出有代表性的案例，收集成案例，用于團隊的提升和警示。

2.4、公共模塊

一個有積累的公司，應該不會從0開始構建自己的項目。總是多多少少有些積累的。代碼同源的模塊如何被復用呢？首先，公司內部要有完善的版本控制機制。任何代碼，全局只有一份。對于svn的版本庫、git的版本庫，有不同的辦法。（svn可以使用externals屬性，保持全局唯一的庫文件。git可以使用subtree,?submodule的辦法建立全局唯一的庫文件。）由于庫代碼導出后，文檔和庫跟著走的，也不存在這不對應的問題。如果發生庫的修改，因為全局就一份庫的代碼。更改完畢，全局都會跟著修改。所以，庫的提交需要更為慎重。需要建立更為嚴謹的修改確認機制。

無論怎么更改，只要每天保證文檔、代碼對應。下載最新的源代碼，使用Doxygen編譯，則可得到最新的文檔。

3、補充說明

文檔代碼同源的思路，可解決實踐中的文檔代碼不一致的問題，但這不是最終目的。長期堅持，達到一個良好的開發習慣和開發氛圍。從而提高項目交付質量和內部的管理水平。達到組織和個人的共同成長。

4、遺留問題

這個方法，是有適用范圍的，我在軟硬結合的項目以及一些純軟件的中小型項目上實施，取得了一些比較好的效果。尚未在比較大型的項目上使用。

另外，方法也需要不少工具配合。

1.如果內部沒有需求管理工具的廠商，可以直接用excel管理，然后自己寫個python工具轉換一下。如果內部有需求管理工具的公司，應該都可以將需求導出成excel，然后通過工具轉換成doxygen接受的文檔。

2.內部的檢查一定要每天堅持，這才是核心中的核心。每天并不耗時，但是卻很重要，量變引起質變。

3.庫的管理需要svn、git等版本控制工具的強力支持，這個需要被管理公司有一定的版本管控水平和能力。

本文原創：?coolbacon?RTEMS?，感謝大神的經驗分享~

開發者 敏捷開發

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。