## 總體原則 1. **As short as possible（如無必要，勿增注釋）**。盡量提高代碼本身的清晰性、可讀性。 1. **As long as necessary（如有必要，盡量詳盡）**。合理的注釋、空行排版等，可以讓代碼更易閱讀、更具美感。 總之，注釋的目的是：**提高代碼的可讀性，從而提高代碼的可維護性。** ## 哪些需要注釋 1. 某段代碼的寫法，需要注釋說明原因時： ```js // Using loop is more efficient than `rest = slice.call(arguments, 1)`. for (i = 1, len = arguments.length; i < len; i++) { rest[i - 1] = arguments[i]; } ``` 2. 添加上注釋，能讓代碼結構更清晰時： ```js init: function(selector, context, rootjQuery) { var match, elem, ret, doc; // Handle $(""), $(null), or $(undefined) if ( !selector ) { ... } // Handle $(DOMElement) if ( selector.nodeType ) { ... } // The body element only exists once, optimize finding it if ( typeof selector === "string" ) { ... } } ``` 3. 有借鑒第三方代碼，需要說明時： ```js // Inspired by https://github.com/jquery/jquery/blob/master/src/core.js function ready() { ... } ``` 4. 當有值的判斷或者選擇，有不同的分支時： ```js // It need to do when the value of a is one or two. if(a === 1 || a === 2) { ... } ``` ## 起始約定 每個源碼文件的開頭，保留為空： ```js define('lego',[],function() { // 源代碼 }); ``` 注意點： 1. 文件頭不注明Author信息，通過README來提供author & contributors。（組件規則，業務代碼需要注明方便查看） ## 注釋書寫規范 1. 源碼中的注釋，推薦用英文。 2. 含有中文時，標點符號用中文全角。 3. 中英文夾雜時，英文與中文之間要用一個空格分開。 4. 注釋標識符與注釋內容要用一個空格分開：`// 注釋` 與 `/* 注釋 */`。 5. 單行注釋用`// 注釋` 與多行注視用 `/* 注釋 */`區分開來，能夠一行注視明白的不寫過多注視 ## JSDoc 注釋 - 不推薦 JSDoc 式注釋，推薦 Backbone 風格的注釋。 - API 請通過 README 等文檔表達清楚。 - 不寫 JSDoc 類文檔，可以讓開發者在寫代碼時更專注于寫代碼，在寫文檔時則更專注于寫文檔。**讓工作解耦，更專注。**