如何保持代碼和規格同步？ - 有沒有好的工具

Question

在我的團隊中，我們有一個很好的源代碼管理系統，我們有很棒的規格。我想解決的問題是如何使規範與代碼保持最新。隨着時間的推移，規範趨於老化並變得過時

製作規範的人傾向於不喜歡源代碼控制，程序員傾向於不喜歡共享點。

我很想聽聽別人使用的解決方案嗎？某處有一個快樂的中間嗎？

Answer 1

我認爲非Sharepoint wiki對於保持文檔是最新的。大多數非技術人員都可以理解如何使用wiki，而大多數程序員會非常樂意使用一個好的wiki。在我看來，Sharepoint中的維基和文檔控制系統是笨重和令人沮喪的。

Mediawiki是一個不錯的選擇。

我真的很喜歡維基，因爲它們是迄今爲止採用和保持的最低痛苦。他們給你自動的版本控制，並且通常對每個人都很直觀。很多公司都希望爲此使用Word，Excel或其他類型的文檔，但將所有內容都聯機並通過通用界面訪問是關鍵。

Answer 2

我不知道你正在描述什麼特別好的解決方案;通常，我所看到的唯一真正保持這種東西同步的解決方案是從源代碼生成文檔的工具（doxygen，Javadoc）。

Answer 3

用於保持文檔與代碼同步的一種技術是literate programming。這將代碼和文檔保存在同一個文件中，並使用預處理器從文檔生成可編譯代碼。據我所知，這是Donald Knuth使用的技術之一 - 如果他在代碼中發現錯誤，他很樂意pay people錢。

Answer 4

沒有。沒有快樂的中間。他們有不同的觀衆和不同的目的。

以下是我作爲建築師和規格作者所學到的：規格幾乎沒有長期價值。克服它。

規格雖然很好地開始編程，但無論您做什麼，都會隨着時間的推移而失去價值。規範的讀者是一個沒有太多洞察力的程序員。那些程序員變身爲不再需要規格的深諳程序員。

規範的一部分 - 特別是概述 - 可能具有一定的長期價值。

如果規格的其餘部分有價值，程序員會讓它們保持最新狀態。

運行良好的是使用代碼中嵌入的註釋和工具來提取這些註釋並生成當前的實時文檔。 Java用javadoc來做到這一點。 Python用epydoc或Sphinx來做到這一點。 C（和C++）使用Doxygen。有很多選擇：http://en.wikipedia.org/wiki/Comparison_of_documentation_generators

概述應該從原來的規格中取出並放入代碼中。

應提取最終文檔。本文檔可以使用規格概述和代碼詳細信息來替換規格。

當需要大修時，會有新的規格。可能需要修改現有的規範。跳轉點是自動生成的規範文檔。規格作者可以從這些開始，並添加/更改/刪除他們心中的內容。

Answer 5

儘可能的規範應該是可執行的，通過rspec或doctest和類似的框架。代碼的規範應該用單元測試和具有良好命名方法和變量的代碼進行記錄。

然後，規範文檔（最好在wiki中）應該能夠提供更高層次的事物概覽 - 並且這些變化不會很快變化或不同步。

這樣的方法肯定會使規範和代碼保持同步，並且當它們不同步時測試將失敗。

這就是說，在許多項目上，上面是一種天空中的餡餅。在那種情況下，洛特是對的，克服它。他們不保持同步。將規範看作開發人員的路線圖，而不是他們所做的文檔。

如果當前規範非常重要，那麼在編寫代碼之後，應該有專門的時間來分配寫入（或重寫）規範的項目。那麼它將是準確的（直到代碼改變）。

所有這些的替代方法是使規範和代碼保持在源代碼控制之下，並檢查檢查以確保規範隨代碼一起更改。它會減慢開發過程，但如果真的那麼重要......