酷殼：?http://CoolShell.cn/?

原文：?http://coolshell.cn/?p=2746

?

在酷殼，有很多文章都提到了代碼注釋，如：《十條不錯(cuò)的編程觀點(diǎn)》、《優(yōu)質(zhì)代碼的十誡》、《整潔代碼的4個(gè)提示》、《惹惱程序員的十件事》等等。今天，某國(guó)外的程序員在這里列舉五種應(yīng)該避免的程序注釋，我覺(jué)得比較有道理，但我覺(jué)得有少數(shù)幾個(gè)觀點(diǎn)也并不絕對(duì)。所以，我把原文的這五種應(yīng)該避免的程序注釋羅列在下面，并放上原作者和我的個(gè)人觀點(diǎn)作為比較。希望對(duì)大家有用。

一、自戀型注釋

（注：原文為Proud，我覺(jué)得“自戀”更好一點(diǎn)）

public class Program {static void Main(string[] args){string message = "Hello World!"; // 07/24/2010 BobConsole.WriteLine(message); // 07/24/2010 Bobmessage = "I am so proud of this code!"; // 07/24/2010 BobConsole.WriteLine(message); // 07/24/2010 Bob} }

原文：這樣的程序員對(duì)于自己的代碼改動(dòng)非常驕傲和自戀，所以，他覺(jué)得需在在這些自己的代碼上標(biāo)上自己的名字。其實(shí)，一個(gè)版本控制工具（如：CVS或Subversion）可以完整地記錄下所有的關(guān)于代碼的改動(dòng)的和作者相關(guān)的一切信息，只不過(guò)不是那么明顯罷了。

陳皓：我同意原文的觀點(diǎn)。在我的團(tuán)隊(duì)里也有這樣的事情發(fā)生。有段時(shí)間我認(rèn)真思考過(guò)這樣的事情，是否應(yīng)該把這樣的事情在代碼中鏟除出去。后來(lái)，我覺(jué)得，允許這樣的行為并不一定是壞事，因?yàn)閮牲c(diǎn)：

?

調(diào)動(dòng)程序員下屬的積極性可能更為重要。即然，這種方式可以讓程序員有驕傲的感覺(jué)，能在寫(xiě)代碼中找到成就感，為什么要阻止呢？又不是什么大問(wèn)題。

調(diào)動(dòng)程序員的負(fù)責(zé)任的態(tài)度。程序員敢把自己的名字放在代碼里，說(shuō)明他對(duì)這些代碼的信心，是想向大家展示其才能。所以，他當(dāng)然知道，如果這段他加入的代碼有問(wèn)題的話，他的聲譽(yù)必然受到損失，所以，他敢這么干，也就表明他敢于對(duì)自己的代碼全面的負(fù)責(zé)。這不正是我們所需要的？！

所以，基于上述考慮，我個(gè)人認(rèn)為，從代碼的技術(shù)角度上來(lái)說(shuō)，這樣的注釋很不好。但從團(tuán)隊(duì)的激勵(lì)和管理上來(lái)說(shuō)，這樣的方式可能也挺好的。所以，我并不阻止也不鼓勵(lì)這樣的注釋。關(guān)鍵在于其是否能有更好的結(jié)果。

二、廢棄代碼的注釋

public class Program {static void Main(string[] args){/* This block of code is no longer needed* because we found out that Y2K was a hoax* and our systems did not roll over to 1/1/1900 *///DateTime today = DateTime.Today;//if (today == new DateTime(1900, 1, 1))//{// today = today.AddYears(100);// string message = "The date has been fixed for Y2K.";// Console.WriteLine(message);//}} }

原文：如果某段代碼不再使用了，那就應(yīng)該直接刪除。我們不應(yīng)該使用注釋來(lái)標(biāo)準(zhǔn)廢棄的代碼。同樣，我們有版本控制工具來(lái)管理我們的源代碼，在版本控制工具里，是不可能有代碼能被真正的物理刪除的。所以，你總是可以從以前的版本上找回你的代碼的。

陳皓：我非常同意這樣的觀點(diǎn)。只要你是廢棄的，就應(yīng)該是刪除，而不是注釋掉。注釋并不是用來(lái)刪除代碼的。也許你會(huì)爭(zhēng)論到，在迭代開(kāi)發(fā)中，你覺(jué)得被注釋的代碼很有可能在未來(lái)會(huì)被使用，但現(xiàn)在因?yàn)榉N種問(wèn)題暫時(shí)用不到，所以，你先注釋著，然后等到某一天再enable它。所以你注釋掉一些未來(lái)會(huì)有的程序。在這樣的情況，你可以注釋掉這段代碼，但你要明白，這段代碼不是“廢棄”的，而是“臨時(shí)”不用的。所以，我在這里提醒你，請(qǐng)不要教條式地在你的程序源碼中杜絕這樣的注釋形式，是否“廢棄”是其關(guān)鍵。

三、明顯的注釋

public class Program {static void Main(string[] args){/* This is a for loop that prints the* words "I Rule!" to the console screen* 1 million times, each on its own line. It* accomplishes this by starting at 0 and* incrementing by 1. If the value of the* counter equals 1 million the for loop* stops executing.*/for (int i = 0; i < 1000000; i++){Console.WriteLine("I Rule!");}} }

原文：看看上面的例子，代碼比注釋還容易讀。是的，大家都是程序員，對(duì)于一些簡(jiǎn)單的，顯而易見(jiàn)的程序邏輯，不需要注釋的。而且，你不需要在你的注釋中教別人怎么編程，你這是在浪費(fèi)時(shí)間去解釋那些顯而易見(jiàn)的東西。你應(yīng)該用注釋去解釋你的代碼功能，原因，想法，而不是代碼本身。

陳皓：非常同意。最理解的情況是你的代碼寫(xiě)得直接易讀，代碼本身就是自解釋的，根本不需要注釋。這是最高境界。注釋?xiě)?yīng)該說(shuō)明下面的代碼主要完成什么樣的功能，為什么需要他，其主要算法怎么設(shè)計(jì)的，等等。而不是解釋代碼是怎么工作的。這點(diǎn)很多新手程序員都做得不夠好。別外，我需要指出的是，代碼注釋不宜過(guò)多，如果太多的話，你應(yīng)該去寫(xiě)文檔，而不是寫(xiě)注釋了。

四、故事型注釋

public class Program {static void Main(string[] args){/* I discussed with Jim from Sales over coffee* at the Starbucks on main street one day and he* told me that Sales Reps receive commission* based upon the following structure.* Friday: 25%* Wednesday: 15%* All Other Days: 5%* Did I mention that I ordered the Caramel Latte with* a double shot of Espresso?*/double price = 5.00;double commissionRate;double commission;if (DateTime.Today.DayOfWeek == DayOfWeek.Friday){commissionRate = .25;}else if (DateTime.Today.DayOfWeek == DayOfWeek.Wednesday){commissionRate = .15;}else{commissionRate = .05;}commission = price * commissionRate;} }

原文：如果你不得不在你的代碼注釋中提及需求，那也不應(yīng)該提及人名。在上面的示例中，好像程序想要告訴其它程序員，下面那些代碼的典故來(lái)自銷售部的Jim，如果有不懂的，你可以去問(wèn)他。其實(shí)，這根本沒(méi)有必要在注釋中提到一些和代碼不相干的事。

陳皓：太同意了。這里僅僅是代碼，不要在代碼中摻入別的和代碼不相干的事。這里你也許會(huì)有以下的爭(zhēng)辯：

有時(shí)候，那些所謂的“高手”逼著我這么干，所以，我要把他的名字放在這里讓所有人看看他有多SB。

有時(shí)候，我對(duì)需求并不了解，我們應(yīng)該放一個(gè)聯(lián)系人在在這里，以便你可以去詢問(wèn)之。

對(duì)于第一點(diǎn)，我覺(jué)得這是一種情緒化。如果你的上級(jí)提出一些很SB的想法，我覺(jué)得你應(yīng)該做的是努力去和他溝通，說(shuō)明你的想法。如果這樣都不行的話，你應(yīng)該讓你的經(jīng)理或是那個(gè)高手很正式地把他的想法和方案寫(xiě)在文檔里或是電子郵件里，然后，你去執(zhí)行。這樣，當(dāng)出現(xiàn)問(wèn)題的時(shí)候，你可以用他的文檔和郵件作為你的免責(zé)證據(jù)，而不是在代碼里干這些事。

對(duì)于第二點(diǎn)，這些需求的聯(lián)系人應(yīng)該是在需求文檔中，如果有人有一天給你提了一個(gè)需求，你應(yīng)該把其寫(xiě)在你的需求文檔中，而不是你的代碼里。要學(xué)會(huì)使用流程來(lái)管理你的工作，而不是用注釋。

最后，關(guān)于故事型的注釋，我需要指出也有例外的情況，我們團(tuán)隊(duì)中有人寫(xiě)注釋喜歡在注釋或文檔里寫(xiě)一些名人名言（如?22條經(jīng)典的編程引言，編程引言補(bǔ)充，Linus Torvalds 語(yǔ)錄 Top 10?），甚至寫(xiě)一些小笑話，幽默的短句。我并不鼓勵(lì)這么做，但如果這樣有利于培養(yǎng)團(tuán)隊(duì)文化，有利于讓大家對(duì)工作更感興趣，有利于大家在一種輕松愉快的環(huán)境下讀/寫(xiě)代碼，那不也是挺好的事嗎？

另外，做為一個(gè)管理者，有時(shí)候我們應(yīng)該去看看程序員的注釋，因?yàn)槟抢锩婵赡軙?huì)有程序員最直實(shí)的想法和情緒（程序員嘴最臟??）。了解了他們的想法有利于你的管理。

五、“TODO”注釋

public class Program {static void Main(string[] args){//TODO: I need to fix this someday – 07/24/1995 Bob/* I know this error message is hard coded and* I am relying on a Contains function, but* someday I will make this code print a* meaningful error message and exit gracefully.* I just don’t have the time right now.*/string message = "An error has occurred";if(message.Contains("error")){throw new Exception(message);}} }

原文：當(dāng)你在初始化一個(gè)項(xiàng)目的時(shí)候，TODO注釋是非常有用的。但是，如果這樣的注釋在你的產(chǎn)品源碼中出現(xiàn)了N多年，那就有問(wèn)題了。如果有BUG要被fix，那就Fix吧，沒(méi)有必要整一個(gè)TODO。

陳皓：是的，TODO是一個(gè)好的標(biāo)志僅當(dāng)存在于還未release的項(xiàng)目中，如果你的軟件產(chǎn)品都release了，你的代碼里還有TODO，這個(gè)就不對(duì)了。也許你會(huì)爭(zhēng)辯說(shuō)，那是你下一個(gè)版本要干的事。OK，那你應(yīng)該使用項(xiàng)目管理，或是需求管理來(lái)管理你下一個(gè)版本要干的事，而不是使用代碼注釋。通常，在項(xiàng)目release的前夕，你應(yīng)該走查一下你代碼中的TODO標(biāo)志，并且做出決定，是馬上做，還是以后做。如果是以后做，那么，你應(yīng)該使用項(xiàng)目管理或需求管理的流程。

上述是你應(yīng)該避免使用的注釋，以及我個(gè)人的一些觀點(diǎn)，也歡迎你留下你的觀點(diǎn)！

from:?http://blog.csdn.net/haoel/article/details/5782907

總結(jié)

以上是生活随笔為你收集整理的五种应该避免的代码注释的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。