title: Web Style Guide 前端代码规范 date: 2015-11-09 00:31:45 categories: - 自用笔记 - 术业专攻 tags: - HTML - CSS - JavaScript permalink: web-style-guide note: 1 ---   在此记录自己已理解并开始遵循的前端代码规范。What How Why ## General style rules ### Filename - Start a file name with a letter and avoid numbers: ``` thousand-and-one-scripts.js ``` > Start a filename with a special sign in order to flag it for a special purpose. - Lower case in filename: > Some operating systems support case sensitive file names and we should not mix the cases to minimize confusion and possible sources for human errors. ### Separator - Use minus (-) sign as separating parts: ``` my-script.js my-camel-case-name.css i-love-underscores.html my-script.js ``` > 1. For readability purpose. Users may mistake the underscores for spaces, as the underlining in the link hides the underscores; > 1. It's a common separator in canonical URL and URL slugs; - Use dot's to separate the clear purpose of this additional meta-data in a filename: ``` my-file.min.css ``` ### Protocol - Omit the protocol portion (http:, https:): ``` html background: url(//static.example.com/images/bg.jpg) ``` > 1. Makes the URL relative—prevents mixed content issues; > 1. Saves file size. ### Text indentation - Indent by 4 spaces at a time. Hitting the Tab key in your text editor should generate four space characters rather than one tab character: ``` html ``` > 1. Make code appearing identical across platforms; > 1. Developers can make adjustments to their editing environments a single time. ### Comments - Comment why it was coded this way and comment the thinking behind. Also include links in your comments to open issues, specifications etc. ``` js var offset = 0; if(includeLabels) { // If the labels are included we need to have a minimum offset of 20 pixels // We need to set it explicitly because of the following bug: http://somebrowservendor.com/issue-tracker/ISSUE-1 offset = 20; } ``` - Use tools to generates API documentation from comments. [JSDoc](http://usejsdoc.org/) or [YUIDoc](http://yui.github.io/yuidoc/) ### Code linting - Writing and following a style guide is a good practice but having an automated process that is enforcing it is even better. ## HTML style rules ### Document type - HTML5 (HTML syntax) is preferred for all HTML documents: ``` html ``` ### Script loading - Add your script element just before the body close tag and add them with a async attribute: ``` html ``` > 1. On modern browsers, this will asynchronously load the script and don't wait for CSSOM to complete before loading; > 1. On older browsers (IE9-), prevent DOM parser blocking, not affecting the user experience too much. ### Type attributes - Omit type attributes for style sheets and scripts: ``` html ``` > HTML5 implies text/css and text/javascript as defaults; > This can be safely done even for older browsers. ### ID in Headings - Give all headings a ID: ``` html

Best practices

``` > 1. IDs for anchors, enter the URL to scroll to the position this element. ### Quotation marks - Use double quotation marks ("") to quote attributes values: ``` html
``` ### 0 values - Do not use units after 0 values unless they are required: ``` css padding-bottom: 0; margin: 0; ``` ### Shorthand Properties - Should be used whenever possible, even in cases where only one value is explicitly set. ``` css border-top: 0; font: 100%/1.6 palatino, georgia, serif; padding: 0 1em 2em; ``` > 1. Useful for code efficiency and understandability. ### Hexadecimal Notation - Use 3 character hexadecimal notation where possible and lower case hex digits: ``` css color: #f3a; color: #d4ddef; ``` ## To be continued ## 参考资料 1. ***Web Styleguide - Style guide to harmonize HTML, Javascript and CSS / Sass coding style*** by **Gion Kunz** on 2014/10/8: 1. ***Isobar Front-end Code Standards*** by **Isobar** on 2015/8/25: 1. ***[译文] Isobar 前端代码规范 及 最佳实践*** by **老码农** on 2015/8/25: