|
很多程序員在寫代碼的時候往往都不注意代碼的可讀性，讓別人在閱讀代碼時花費更多的時間。其實，只要程序員在寫代碼的時候，注意為代碼加注釋，并以合理的格式為代碼加注釋，這樣就方便別人查看代碼，也方便自己以后查看了。下面分享十個加注釋的技巧： 1. 逐層注釋 為每個代碼塊添加注釋，并在每一層使用統一的注釋方法和風格。例如： 針對每個類：包括摘要信息、作者信息、以及最近修改日期等； 針對每個方法：包括用途、功能、參數和返回值等。 在團隊工作中，采用標準化的注釋尤為重要。當然，使用注釋規范和工具(例如C#里的XML，Java里的Javadoc)可以更好的推動注釋工作完成得更好。 2. 使用分段注釋 如果有多個代碼塊，而每個代碼塊完成一個單一任務，則在每個代碼塊前添加一個注釋來向讀者說明這段代碼的功能。例子如下： // Check that all data records // are correct foreach (Record record in records) { if (rec.checkStatus()==Status.OK) { . . . } } // Now we begin to perform // transactions Context ctx = new ApplicationContext(); ctx.BeginTransaction(); 3. 在代碼行后添加注釋 如果多行代碼的每行都要添加注釋，則在每行代碼后添加該行的注釋，這將很容易理解。例如： const MAX_ITEMS = 10; // maximum number of packets const MASK = 0x1F; // mask bit TCP 在分隔代碼和注釋時，有的開發者使用tab鍵，而另一些則使用空格鍵。然而由于tab鍵在各編輯器和IDE工具之間的表現不一致，因此最好的方法還是使用空格鍵。 4. 不要侮辱讀者的智慧 避免以下顯而易見的注釋：寫這些無用的注釋會浪費你的時間，并將轉移讀者對該代碼細節的理解。 if (a == 5) // if a equals 5 counter = 0; // set the counter to zero website = "http://www.xxx.net.cn"; // this is a website 5. 禮貌點 避免粗魯的注釋，如：“注意，愚蠢的使用者才會輸入一個負數”或“剛修復的這個問題出于最初的無能開發者之手”。這樣的注釋能夠反映到它的作者是多么的拙劣，你也永遠不知道誰將會閱讀這些注釋，可能是：你的老板，客戶，或者是你剛才侮辱過的無能開發者。 6. 關注要點 不要寫過多的需要轉意且不易理解的注釋。避免ASCII藝術，搞笑，詩情畫意，hyperverbosity的注釋。簡而言之，保持注釋簡單直接。 7. 使用一致的注釋風格 一些人堅信注釋應該寫到能被非編程者理解的程度。而其他的人則認為注釋只要能被開發人員理解就行了。無論如何，Successful Strategies for Commenting Code已經規定和闡述了注釋的一致性和針對的讀者。就個人而言，我懷疑大部分非編程人員將會去閱讀代碼，因此注釋應該是針對其他的開發者而言。 8. 使用特有的標簽 在一個團隊工作中工作時，為了便于與其它程序員溝通，應該采用一致的標簽集進行注釋。例如，在很多團隊中用TODO標簽表示該代碼段還需要額外的工作。 int Estimate(int x, int y) { // TODO: implement the calculations return 0; } 注釋標簽切忌不要用于解釋代碼，它只是引起注意或傳遞信息。如果你使用這個技巧，記得追蹤并確認這些信息所表示的是什么。 9. 在代碼時添加注釋 在寫代碼時就添加注釋，這時在你腦海里的是清晰完整的思路。如果在代碼最后再添加同樣注釋，它將多花費你一倍的時間。而“我沒有時間寫注釋”，“我很忙”和“項目已經延期了”這都是不愿寫注釋而找的借口。一些開發者覺得應該write comments before code，用于理清頭緒。例如： public void ProcessOrder() { // Make sure the products are available // Check that the customer is valid // Send the order to the store // Generate bill } 10. 為自己注釋代碼 當注釋代碼時，要考慮到不僅將來維護你代碼的開發人員要看，而且你自己也可能要看。用Phil Haack大師的話來說就是：“一旦一行代碼顯示屏幕上，你也就成了這段代碼的維護者”。因此，對于我們寫得好(差)的注釋而言，我們將是第一個受益者(受害者)。(tjwzjs) |
