爲什麼我們沒有在源代碼中嵌入代碼的設計文檔是否有原因？

Question

我們不能在源代碼本身編寫源代碼的設計文檔嗎？我想像Doxygen，但重點從實施到設計。基本上（而且令人興奮的是）在源文件的末尾有一大塊markdown。每當我創建一個新的源文件（並開始在清晰的白頁中編寫）時，我認爲如果寫在那裏的第一個東西是筆記，想法和想法，那我會覺得很愉快。探索模塊希望/需要/夢想完成什麼。也許接近源代碼會鼓勵更頻繁和熱切地關注它的文檔？

或者我可能應該花時間製作自我記錄代碼。

Answer 1

在源代碼中嵌入設計的一個問題是源代碼佈局/結構可能太細緻，無法在文件級別進行記錄 - 這是通過編寫良好的，乾淨的自編寫代碼來涵蓋的。如果你是一個重構工程師，你可能會有很多小文件，並且記錄每一個文件都是毫無意義的（因爲閱讀所有的備註將非常困難）。這就是說，在命名空間/模塊/組件級別上有更通用的設計說明（自述文件）可能非常有用 - 「如果我第一次看到這個，我想知道什麼」類型的文檔，用純英文書寫，並且有明確的問題，決定等等。

Answer 2

我做的很多事情是我首先創建一個空方法存根，並將其中的技術設計作爲註釋添加到每行中。然後，在評論的每一行之後，我寫出了符合設計說明的代碼。

Answer 3

您可以這樣做 - 它被稱爲Literate Programming，由Donald Knuth發明。至於自我記錄代碼，我只能說我從來沒有見過任何代碼。

Answer 4

誰說我們不？

文檔XML或Doxygen文檔註釋（例如一個類）是描述一個類如何工作的理想場所。

從歷史上看，嵌入式文檔（存儲在源文件中）最大的問題是它必須基於文本，因此很難編寫和讀取，尤其是在需要截圖和圖表的情況下。但是，使用Visual Studio 2010現在很容易將其他信息嵌入到源代碼文件（位圖圖像​​等）中，所以我認爲您很快會看到一些擴展出現，允許您將wysiwyg文檔直接嵌入到代碼中。與此同時，對於需要截圖和圖表的更復雜的文檔，我們只需將文檔與代碼一起存儲在「文檔」文件夾中 - 因此，如果您希望使用裝配，則裝配的概述/設計是由代碼旁邊的版本文檔給出。這並不完全嵌入到源代碼中，但當你需要時，它總是接近手。