鏈接代碼結構和架構文檔

比方說，我寫一個新的通信協議（我會用這個例子TFTP），並在Word文檔中我下表有（格式可能不同）：鏈接代碼結構和架構文檔

Opcode | 2 bytes 
filename | string 
padding | 1 byte = 0 
mode  | string 
padding | 1 byte = 0

現在，當我去寫的代碼，我會做一些類型的結構，像這樣：

class TFTP_packet: 
    short opcode 
    string Filename 
    byte padding=0 
    string mode 
    byte padding2=0

這對我來說好像我做一些重複性的工作。目前我正在使用正則表達式來加快速度，但有沒有什麼方法可以封裝這些數據，以便可以方便地在文檔中顯示，還可以輕鬆轉換爲代碼？有沒有辦法將文件中的結構分開？

來源

2011-03-25 stbtrax

您是否考慮過使用CASE解決方案，如Visio或Dia而不是Word文檔？ – 2011-03-25 17:27:05

規範（協議）定義了代碼應該做什麼;它不應該經常改變，並且您不希望從源代碼重新生成規範，以免代碼錯誤成爲規範錯誤。

CASE工具嘗試保持詳細設計和生成源同步，但很少成功。祝你好運，如果你選擇的路徑。通常使用設計文檔來初步開發代碼，但是對於檔案而言，它卻成爲一個無人維護的歷史文物。

另一方面，根據需要可以相對容易地從代碼生成最新的文檔 - 例如， javadoc（java）或doxygen（C++）等等。這裏的聖盃確實是單一來源內容的每一位（不是雙關語），並生成最終產品。也就是說，您不想在兩個（或更多）位置維護相同的描述，相同的表格，相同的數據結構。這並不意味着每件事都必須記錄在一個地方（msword XOR來源）：相反，您可能想要將生成的內容（來自源代碼）合併到現有的外部文檔中（在文檔中）。

但是，爲了更進一步，我建議不要使用Word（不靈活，依賴於平臺，很難自動化），而是使用OpenOffice（LibreOffice）「master」文檔（*.odm）合併常規文檔（*.odt）和生成的圖像&文本片段（從您的源代碼或甚至測試程序輸入/輸出生成）。構建最終的文檔可以編寫腳本（包括pdf生成），甚至可以整合到整個源代碼構建過程中。

來源

2012-06-07 08:28:25 michael

鏈接代碼結構和架構文檔

回答

相關問題