在軟件開發(fā)的世界中，撰寫代碼注釋和文檔通常被認為是一項重要的工作，它可以幫助其他開發(fā)者理解你的代碼，更容易地維護和擴展它。然而，在實際操作中，很多程序員卻選擇不寫注釋或文檔。以下列出了程序員們在實踐中經(jīng)常提到的十大理由，這些理由不僅揭示了他們對于撰寫文檔和注釋的觀點，也反映出軟件開發(fā)行業(yè)中一些深層次的問題。
我們并非開發(fā)面向外部的 SDK，所以撰寫文檔似乎毫無必要。再者，寫文檔并不能作為 KPI 的一部分。
實際上，是因為工期過于緊迫。如果有充裕的時間，我甚至愿意增加單元測試。但現(xiàn)實是，剛剛完成一個項目，就有新的任務(wù)立刻接踵而至，沒有時間讓我們稍作休息。
有的時候，我們確實有文檔，但卻無法及時更新，全都是過時的內(nèi)容。這種情況下，有文檔反而不如沒有，查閱文檔往往不如直接看代碼，但卻讓人誤以為有文檔就很方便。
在我的代碼中，我?guī)缀醪粚懽⑨?，API文檔我會寫在 wiki 中，代碼規(guī)范，命名也規(guī)范。當你的代碼規(guī)范、命名規(guī)范時，其實沒有必要寫注釋。目錄名、函數(shù)名和變量名就是最好的注釋。
如果你的架構(gòu)設(shè)計得很好，代碼易讀、易擴展，任何人都可以接手。這就讓你成為一個“可有可無”的人。
如果你的代碼寫得很好，基本上沒有 bug，而你又每天都不需要加班，你就被視為工作態(tài)度不積極的人。
如果你的代碼寫得很差，bug 層出不窮，每天都必須加班，你就成了公司的中堅力量。
如果你的架構(gòu)一片混亂，除了你自己沒有人敢接觸你的代碼，那你就是公司的重要人物，沒有你，項目就會崩潰。
撰寫文檔和注釋，需要體諒開發(fā)者的感受。正常的開發(fā)工時，我們至少需要一半的時間來寫文檔。如果沒有這個時間，自然就不能寫，這是毫無疑問的。
寫注釋是為了將來自己查看，而不是給后續(xù)接手的人看。如果自己都能看懂，就沒必要寫注釋。代碼的原則是：沒有注釋也能看懂的代碼，才是最好的代碼。
以上是程序員們不寫代碼注釋和文檔的十大理由，這些理由充分反映出他們在實際工作中的困擾和壓力。但是，這并不意味著我們就可以忽視文檔和注釋的重要性。盡管在某些情況下，這些理由可能有一定的道理，但是好的代碼注釋和完善的文檔無疑可以使我們的工作更加有效率，使其他開發(fā)者更容易地理解和維護我們的代碼。為此，我們需要尋找一個平衡點，以滿足項目的需求，同時也盡可能地減少對開發(fā)者的負擔。
