我即將完成一個馬拉松9個月的項目 - 一個具有超過70萬行代碼的Web應用程序。問題是我很少使用註釋，從來沒有使用過javadoc，也從來沒有保存過任何好的文檔。 （哦內疚!! :)）追溯記錄+評論的策略
我現在需要把重點放在我的業務的非技術方面，並將這個巨人關閉到維護和新功能的編程團隊。那麼我該怎麼做......寫出最有用的評論/文檔是什麼？追溯文檔的最佳策略是什麼？ （有沒有關於這個問題的書籍？）
PS。感謝您的幾個月和幾個月的幫助Stack Overflow。一年前我幾乎不知道HTML。你讓我度過了這一切！
70K行不是那麼大。它可能比你通常工作的項目要大，但至少它不是很大，一個人不能理解它的大部分。這可能是你首先遇到麻煩的原因。它不會讓你通過每個文件並寫幾句關於班級的功能。
70K行太大而無法強加於某人或某個團隊，而沒有對它的作用和原因做出某種解釋。至少編寫一份路線圖，詳細解釋項目的內容，組織結構，哪些部分對於績效非常重要，或者如何確定哪些部分是重要的以滿足需求，哪些部件需要工作。如果您對該項目有任何書面要求，則應包含這些要求。
我想象一下，在你讓團隊工作在這個沒有記錄的代碼堆之前，你打算至少坐下來看看團隊成員一天，並給他們一個方向。寫下你希望在這個方向告訴他們的一切。在你真正與他們見面之前，給團隊一些文件和一些時間閱讀。現在，您可以利用這一天與他們一起回答他們的問題來完善文檔。確保答案將其納入文檔的下一個修訂版本。讓團隊的首要任務是解決您創建的問題。這將幫助他們準備好開始實施新功能。
可以回答團隊對可預見未來的問題。創建某種系統來組織和保存您提供的信息。一個維基似乎很明顯，但你也想確保新的問題得到注意和迅速回答。缺陷跟蹤系統可以很好地工作。所以可能會有某種Q &像SO這樣的格式。
改變你對文檔的態度。從錯誤中學習，改變你的方式，並鼓勵/堅持花時間記錄他們所做事情的人。嘗試通過連接缺陷跟蹤系統和版本控制系統儘可能自動創建文檔。爲您的員工提供他們需要的資源以生成有用的文檔。讓某人負責文檔。
我傾向於像你一樣做，追溯評論，如果我評論。但是，當我這樣做時，我嘗試主要記錄我的自定義函數&類，以及我的代碼的重要部分。我注意到的東西，如：
評論時做的最好的事情的解釋是想發生什麼了，如果你突然消失並無法解釋你的代碼。接手的開發人員需要了解和理解什麼？顯然，你不應該讓你的代碼太抽象（也就是說，除非適用，否則只能使用變量名稱，如$ x，$ y，$ z）。
我有一條也是唯一一條建議。用手做，並解釋**爲什麼**代碼做它做的事，而不是*它做了什麼。它所做的是顯而易見的，但「爲什麼」不應該是未知數。除非你知道爲什麼某些事情是以某種方式完成的，否則某些東西可能看起來非常瘋狂。 – Charles 2011-03-26 05:23:27
根據需要填寫評論。如果代碼是自我解釋的，那麼評論就會受到阻礙。但是，如果代碼做了一些奇怪的事情，那麼你絕對應該在那裏使用一些評論。 – 2011-03-26 05:45:25