程式設計師應該避免的5種程式碼註釋
本文由碼農網 – 小峰原創翻譯,轉載請看清文末的轉載要求,歡迎參與我們的付費投稿計劃!
你有沒有這樣的經歷:別人審查過你的程式碼之後給出的註釋,你認為是沒有必要的?註釋程式碼是為了提高程式碼的可讀性,目的是為了能讓其他人更容易理解你的程式碼。
我特別討厭這5種註釋型別以及製造它們的程式設計師。希望你不是其中之一。
1.自以為很了不得的程式設計師
public class Program { static void Main(string[] args) { string message = "Hello World!"; // 07/24/2010 Bob Console.WriteLine(message); // 07/24/2010 Bob message = "I am so proud of this code!"; // 07/24/2010 Bob Console.WriteLine(message); // 07/24/2010 Bob } }
這個程式設計師自認為寫了一段很了不得的程式碼,所以覺得有必要用自己的名字對每行程式碼進行標記。實施版本控制系統(VCS)能實現對程式碼變更的問責,但是也不會這麼明顯知道誰應對此負責。
2.過時的程式設計師
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); //} } }
如果一段程式碼已不再使用(即過時),那就刪除它——不要浪費時間給這些程式碼寫註釋。此外,如果你需要複製這段被刪除的程式碼,別忘了還有版本控制系統,你完全可以從早期的版本中恢復程式碼。
3.多此一舉的程式設計師
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!"); } } }
我們都知道基礎的程式設計邏輯是如何工作的——所以你不需要多此一舉來解釋這些顯而易見的工作原理,雖然說你解釋得很happy,但這只是在浪費時間和空間。
4.愛講故事的程式設計師
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; } }
如果你一定要在註釋裡提及需求,那麼不要涉及別人的名字。銷售部門的Jim可能會離開公司,而且很有可能大多數程式設計師根本不知道這是何許人也。不要在註釋裡提及不相干的事實。
5.“以後再做”的程式設計師
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); } } }
這種型別的註釋包含了上面所有其他型別。如果是在專案的初始開發階段,這種待做註釋是非常有用的,但如果是在幾年後的產品程式碼——那就會出問題了。如果有什麼需要修復的,立馬解決,不要把它擱置一邊,“以後再做”。
如果你也常常犯這樣的註釋錯誤,如果你想了解註釋的最佳做法,我建議你閱讀類似於Steve McConnell寫的《Code Complete》這樣的好書。
另外筆者也推薦你閱讀以下內容:《9個最有趣的程式碼註釋》、《程式碼註釋中的5要與3不要》
譯文連結:http://www.codeceo.com/article/5-types-comment-we-avoid.html
英文原文:5 Types of Programming Comments to Avoid
翻譯作者:碼農網 – 小峰
[ 轉載必須在正文中標註並保留原文連結、譯文連結和譯者等資訊。]
相關文章
- 程式設計師是否有義務做好程式碼的註釋?你做好程式碼註釋了嗎?程式設計師
- 註釋之重——程式設計師與程式碼可維護性程式設計師
- 為什麼說程式碼註釋是程式設計師必備的技能?程式設計師
- 程式設計師應該如何找工作呢?程式設計師
- 程式設計師你應該勇敢說不程式設計師
- 程式設計師應該少做些"工作" - johnwhiles程式設計師While
- 39個史詩級奇葩程式碼註釋,程式不會崩,但程式設計師會!程式設計師
- 優秀的程式設計師真的不寫註釋嗎?程式設計師
- Java程式設計師必須掌握的5個註解!Java程式設計師
- 程式設計師永遠不應該相信"抽象“程式設計師抽象
- 有經驗的程式設計師應該如何提升自己程式設計師
- 3 年 Java 程式設計師應該具備的技能!Java程式設計師
- 程式設計師最應該知道的一些事程式設計師
- 程式設計師應該造的五大輪子程式設計師
- Java程式設計師應該在2018年學習三種JVM語言Java程式設計師JVM
- Java程式設計師應該知道的20個有用的庫Java程式設計師
- 程式設計師都不知道的5種將死的程式語言程式設計師
- 21個奇葩註釋,程式設計師看了都點贊程式設計師
- 你應該知道的 5 種 TypeScript設計模式TypeScript設計模式
- Java之列舉, 程式設計師應該掌握的開發技巧“簡潔易懂又安全的程式碼”Java程式設計師
- php程式設計師應具有的7種能力PHP程式設計師
- 站在風口上的程式設計師,就應該有高收入!程式設計師
- 有趣的程式碼註釋
- 作為程式設計師,有沒有讓你感到既無語又崩潰的程式碼註釋?程式設計師
- 淺談:合格的Java程式設計師應該具備的能力Java程式設計師
- 1024程式設計師節,向用程式碼改變世界的程式設計師致敬!程式設計師
- 選Python還是選Java?2020年,頂尖程式設計師最應該掌握的7種程式語言PythonJava程式設計師
- 程式設計師的中年該如何度過程式設計師
- Java 程式設計師都該懂的 HashMapJava程式設計師HashMap
- 從程式碼的風格看出六種不同型別的程式設計師型別程式設計師
- 每個程式設計師都應該知道的下一個程式語言——Kotlin程式設計師Kotlin
- 好程式設計師教程分享Java註解和運用註解程式設計程式設計師Java
- 程式設計師應該怎樣和領導相處?程式設計師
- 年終了,程式設計師應該這樣談加薪!程式設計師
- 程式設計師該不該主動提加薪?程式設計師
- 程式設計師幸福感拉滿:一鍵為程式碼自動生成註釋的工具,拿走不謝!程式設計師
- 程式設計師永遠不要再犯的5個程式設計bug程式設計師
- 5位女性程式設計師的自白:計算機不撒謊;女程式設計師的程式碼一樣也很棒程式設計師計算機
- CSS程式碼註釋CSS