請註釋你那該死的程式碼

我站出來就是為了要說一句：

請註釋你那該死的程式碼。

每次我遇到一個程式設計師——有時是相當高水的——總發現他會認為：你並不需要給你的程式碼加註釋。我要說，這就是胡說八道。我很長時間以來一直這麼表 達。問題是，讓事情改變要比你想象的難。雖然我們正處在努力編寫那些討厭的程式碼、準備釋出一些會令人驚歎的新東西的緊要關頭，我們仍然幾乎註釋所有的東 西。沒有任何藉口不去做這些事情。每隔3到7行程式碼，你就能看到有長篇的社論發表。有時，幾百行程式碼裡，你就能找到一個很好的笑話。

錯誤的藏身之處

看，一個是你想要的，一個是你實現的。你的bug就在這兩者之間。如果寫了註釋，你就是在告訴我你想要的。而你的程式碼中告訴我你是如何去做的。程式的缺陷要麼存在於你想要的想法中，要麼，需求是對的，而你的程式碼有問題。請幫助我，讓我知道究竟是哪個錯了。

不要偷懶

一個常見的反對聲音是：我聽說，註釋經常會過期，因為程式碼會經常更新，而註釋不會。你不更新註釋嗎？你的同事也不？不要偷懶，不要養成一個讓人認為 偷點兒懶無所謂的文化氛圍。告訴同事你是如何一絲不苟的註釋程式的，讓他們知道你也希望他們這樣去做。說不註釋是因為怕某人或某些地方在將來會造成你的錯 誤，這只是在找藉口。

你是有經驗的人

人本無知，這很自然，但你是有經驗的人。因此，你有義務教育那些需要學習的人。你的註釋會指導那些正在閱讀你的程式碼的人。告訴他們為什麼在這裡要用 Tuple資料結構，而不是用其它的(更好的做法是附加一個stack overflow或dotnetperls上的連結 … 你完全可以做到這些，不是嗎？)你在這走了一個什麼捷徑？如果不走捷徑你就不能按時釋出，所以，告訴這些新手你遇到的特殊情況。否則的話，最終你的不好的 程式碼將會被四處複製，四處散播。看！你寫的爛程式碼變成了公司的程式模板！完全沒有註釋！

你會打字

我的招聘過程有一部分是白板程式設計，一部分是鍵盤程式設計。所有好的程式設計師都是打字高手。就說你每分鐘能打出40-60詞。那請你告訴我，為什麼在你機槍 掃射似的編寫程式碼時不加上註釋呢？當然，你可以花30秒時間告訴我，程式碼寫的這樣一團糟是因為搞業務的那個傢伙需要程式在本週釋出而換回不菲的7.5萬美 元。可是下個月呢？這些程式碼不要了？封存到石頭裡了？我知道這些程式碼是在幹什麼。但請告訴我你的意圖。

你在一天天變老

聽我說，我程式設計已經很久了，也許早在你上中學之前。我仍然在程式設計，我仍然喜歡程式設計。有朝一日，你也會變的跟我一樣老。如果你到了像我一樣(那時我已 經沒有能力再教育你)，那時，有太多的層，有太多的抽象，有太多的技術架構，你無法完全記住。你的註釋就能出來指導你。它們會告訴你，6個月前，你是用這 種方法、這種模式實現的，而且這樣做只是為了炫耀。如果你是一個真正優秀——並且仍然在做程式設計的程式設計師——你會認識到，這些程式碼寫的很爛，你現在需要以不 同的方式重新實現它。而你仍然有你的註釋來讓你回憶起當時的想法和為什麼這樣做。

所以，請註釋你那該死的程式碼。

 

[本文英文原文連結：Comment your damn code ]

譯文：http://www.aqee.net/comment-your-damn-code/