目錄
1、問題起源
2、解決方案
2.1、需求和代碼對應
2.2、每日檢查
2.3、飛行檢查
2.4、公共子產品
3、補充說明
4、遺留問題
文檔代碼同源，故名思意，就是文檔和代碼都寫在源代碼檔案裡。這樣可以：
1、修改代碼的時候就及時修改文檔，使得文檔和代碼及時保持一緻；
2、閱讀代碼時，增加代碼的可讀性。評審代碼的時候，尤其是修改時後，即對文檔一同評審。結合研發流程、評審的配合，可促使代碼、文檔的開發逐漸走向一一對應，逐漸向高品質發展，同時也能提高團隊素質。
網際網路行業和一些物聯網行業，軟體開發都提倡靈活開發，靈活開發為何物？(附件介紹。)這裡列出靈活的宣言：
個體和互動高于流程和工具
工作的軟體高于詳盡的文檔
客戶合作高于合同談判
響應變化高于遵循計劃
也就是說，盡管右項有其價值，
我們更重視左項的價值
很多公司所謂的靈活，很大程度上就是開發代碼，應該有的必要文檔可能都是不全的。因為要趕工，因為市場的巨大壓力，文檔代碼對應不上司空見慣。更有甚者，壓根就沒有文檔。這裡造成了很多隐性的問題。
1.沒有合适的文檔，随着時間的推移，一些技術要點，設計要求，設計思路随着時間，盡歸塵土。這些通過市場、技術、商業等各個次元試錯的來的寶貴經驗和知識無法傳承，是一種浪費，更是一種低效組織的表現。
2.關鍵崗位的開發人員一旦流失，産生的技術、知識斷崖，短期内難以補足。
3.新人的進入，需要長時間的消化了解。
4.代碼的評審和檢查不嚴格，想怎樣改就怎樣改，隻要外在的功能是正常的。那就是沒有問題的。為很多問題埋下了伏筆和隐患。
靈活中有一個觀點，竊以為是無比正确的：沒有什麼文檔比代碼更準确。但這個觀點又是比較危險的：
1.可運作的功能正确的代碼的确是沒有什麼比其更準确的了。但是，代碼畢竟是寫給機器運作的，個人的能力、習慣等都不一緻，其他人了解起來必然費勁。有一些飽含技巧的寫法可能是需求的需要，也可能是個人炫技的需要；其他人又怎能看透全部呢？代碼畢竟是非自然語言，有時候能看得懂代碼，是以犧牲速度為代價的，總之，問題比較多。
2.潛台詞是，文檔不重要。
總之，文檔、代碼的問題，不僅困擾着程式員，也困擾着公司。那麼怎麼找一個合适的方法解決這個問題呢？
想想程式員為什麼寫或修改代碼？我想即使是為了拯救地球和全宇宙，從微觀上講，也符合下列情況之一：
1.實作需求。是的，這怕是程式員寫/修改代碼的第一大原因了。
2.抓Bug。程式員實作需求的副産品：八阿哥(bug)。把它送走，是我們改代碼的第二大驅動。
3.其他原因，諸如設計不足，可了解性不好啦，子產品用起來不爽啦，封裝不夠簡潔實用，有一些程式員還有潔癖。這可能都是修改代碼的原因。但從本質上來講，也是滿足需求的修改。每個産品需求定義之外，都有灰色邊界。需求提得越清楚，灰色地帶就越少。閱讀性不好、子產品用起來不爽，可能在需求裡沒有提出來。有些作為需求提出來，也是可以的。比如說，對于産品某個子產品的要求，必須使用什麼标準技術或子產品，或者必須滿足下一代的複用等。至于潔癖，團隊沒有定義團隊的寫法，那麼沖突修改是必然的。
代碼中所有的修改都可歸為這三類，更進一步，大部分應該是前兩類。開源世界有一個很好用的工具是Doxygen。它的作用就是把代碼裡的特殊注釋抽取出來變為文檔(一個類似Latex的工具，非所見即所得的文檔編輯工具)。我們的思路就是，利用Doxygen工具，将代碼和文檔的開發變為同步過程。由于文檔含在代碼裡，也意味着Doxygen的文檔也是文本，在版本庫的管理下，能精确的看到每一個比特的修改。(後面有文章做一個的Doxygen介紹。)這裡簡單的介紹一下Doxygen。
Doxygen 是一個程式的文檔産生工具，可将程式中的特定注釋轉換成為說明檔案。比如說對于以下這段注釋：
以上經過Doxygen抽取編譯後，會生成一個綜合性文檔，可在裡面查到：
即使我們不用doxygen編譯，寫在代碼裡的注釋，也是不影響我們了解的。隻是編譯後，查閱起來更友善。
這是我們實作文檔代碼同源的基礎。但文檔代碼的同源不僅僅是把代碼和文檔合成一個源代碼檔案。我們要做得是：
1.需求要和代碼中的各個實作子產品對應起來；
2.文檔的修改、代碼的修改同步進行，每天由工程師交叉檢查并給出評語；
3.進階技術人員定期整理代碼問題，形成案例；
4.如果是公共子產品，項目進行過程中，定期整理其Bug，問題，維護其可用性。
開發一款産品，首先要提需求，需求開發出來，大抵是這樣的：
需求提出了方方面面的要求，一般，需求的配置設定表也跟在後面，用于訓示這個需求都由那些子產品實作。
緊接着下來是軟硬體的概要或者詳細設計，有些公司為了節省，就隻有設計；有的幹脆就連設計也省了，走“靈活"路線。這個并不重要。
Doxygen支援自由頁面，可以寫一個Python的小工具，将excel的需求表轉化為 txt的文本檔案，被doxygen所識别。
這樣做得好處：
1.需求隻要經常用版本庫追蹤，誰改了一個字，改了什麼都會清清楚楚。
2.程式員查閱需求會更加簡便。同時，每日的檢查強調，需求的修改，可能會帶來代碼的修改；Bug的修改可能帶來代碼的修改，需求的修改。進而強調需求的定義作用，主動維護需求的前後一緻。
如子產品中編寫時，說明實作了哪些需求。
這些都是超文本标簽，點選後迅速轉到需求定義處可檢視。
該方法的核心内容，就是每日檢查。一個程式員每天的代碼産量最多可達上千行(非每日平均産量)。如果是更改Bug，可能一天大部分的時間用于分析跟蹤上。正真的修改并不多。每日送出版本庫後，由其他程式員或者部門經理檢查代碼及修改，檢查的内容如下：
1.代碼修改是否有效，符合組織内部的規定；
2.文檔和代碼是否對應。
與需求類似，寫一個Excel表格，包含：子產品；檢查人；日期；問題描述的跟蹤表；檢查完成後送出至版本庫，由對應的工程師承接修改。
每次檢查，檢查文檔、代碼的問題，通過版本庫可以很輕松的跟蹤相關的修改。并定位修改是否合理。
為了防止檢查流于形式，定期對一些具有代表性的問題做總結。進階技術人員需要做一些飛行檢查，定期的抽查檢查表以及文檔代碼的對應情況。并從問題中選出有代表性的案例，收內建案例，用于團隊的提升和警示。
一個有積累的公司，應該不會從0開始建構自己的項目。總是多多少少有些積累的。代碼同源的子產品如何被複用呢？首先，公司内部要有完善的版本控制機制。任何代碼，全局隻有一份。對于svn的版本庫、git的版本庫，有不同的辦法。（svn可以使用externals屬性，保持全局唯一的庫檔案。git可以使用subtree, submodule的辦法建立全局唯一的庫檔案。）由于庫代碼導出後，文檔和庫跟着走的，也不存在這不對應的問題。如果發生庫的修改，因為全局就一份庫的代碼。更改完畢，全局都會跟着修改。是以，庫的送出需要更為慎重。需要建立更為嚴謹的修改确認機制。
無論怎麼更改，隻要每天保證文檔、代碼對應。下載下傳最新的源代碼，使用Doxygen編譯，則可得到最新的文檔。
文檔代碼同源的思路，可解決實踐中的文檔代碼不一緻的問題，但這不是最終目的。長期堅持，達到一個良好的開發習慣和開發氛圍。進而提高項目傳遞品質和内部的管理水準。達到組織和個人的共同成長。
這個方法，是有适用範圍的，我在軟硬結合的項目以及一些純軟體的中小型項目上實施，取得了一些比較好的效果。尚未在比較大型的項目上使用。
另外，方法也需要不少工具配合。
1.如果内部沒有需求管理工具的廠商，可以直接用excel管理，然後自己寫個python工具轉換一下。如果内部有需求管理工具的公司，應該都可以将需求導出成excel，然後通過工具轉換成doxygen接受的文檔。
2.内部的檢查一定要每天堅持，這才是核心中的核心。每天并不耗時，但是卻很重要，量變引起質變。
3.庫的管理需要svn、git等版本控制工具的強力支援，這個需要被管理公司有一定的版本管控水準和能力。
本文原創： coolbacon RTEMS ，感謝大神的經驗分享~