Web Style Guide 前端代码规范

自用笔记术业专攻

自用笔记：本文属于自用笔记，不做详解，仅供参考。

　　在此记录自己已理解并开始遵循的前端代码规范。What How Why

General style rules

Filename

  • Start a file name with a letter and avoid numbers:
    1
    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:
    1
    2
    3
    4
    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;
  2. 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:
1
my-file.min.css

Protocol

  • Omit the protocol portion (http:, https:):
1
2
<script src="//cdn.com/foundation.min.js"></script>
background: url(//static.example.com/images/bg.jpg)
  1. Makes the URL relative—prevents mixed content issues;
  2. 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:
1
2
3
4
5
6
7
<ul>
    <li>Fantastic</li>
    <li>Great</li>
    <li>
        <a href="#">Test</a>
    </li>
</ul>
  1. Make code appearing identical across platforms;
  2. 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.
1
2
3
4
5
6
7
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 or 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:
1
<!DOCTYPE html>

Script loading

  • Add your script element just before the body close tag and add them with a async attribute:
1
2
3
4
5
6
7
8
9
10
<html>
    <head>
        <link rel="stylesheet" href="main.css">
    </head>
    <body>
        <!-- body goes here -->

        <script src="main.js" async></script>
    </body>
</html>
  1. On modern browsers, this will asynchronously load the script and don’t wait for CSSOM to complete before loading;
  2. 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:
1
2
<link rel="stylesheet" href="main.css">
<script src="main.js"></script>

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:
1
<h3 id="best-practices">Best practices</h3>
  1. IDs for anchors, enter the URL to scroll to the position this element.

Quotation marks

  • Use double quotation marks (“”) to quote attributes values:
1
<div class="news-article"></div>

0 values

  • Do not use units after 0 values unless they are required:
1
2
padding-bottom: 0;
margin: 0;

Shorthand Properties

  • Should be used whenever possible, even in cases where only one value is explicitly set.
1
2
3
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:
1
2
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: https://github.com/gionkunz/chartist-js/blob/develop/CODINGSTYLE.md
  2. Isobar Front-end Code Standards by Isobar on 2015/8/25: http://isobar-idev.github.io/code-standards/
  3. [译文] Isobar 前端代码规范 及 最佳实践 by 老码农 on 2015/8/25: http://coderlmn.github.io/code-standards/

本文标题:Web Style Guide 前端代码规范

文章作者:MOxFIVE

发布时间:2015-11-09, 00:31

最后更新:2016-04-20, 11:51

更新历史: Blame, History文本模式: .md Raw

原始链接:http://MOxFIVE.xyz/2015/11/09/web-style-guide/

许可协议: "署名-非商用-相同方式共享 3.0" 转载请保留原文链接及作者。

文章目录
  1. 1. General style rules
    1. 1.1. Filename
    2. 1.2. Separator
    3. 1.3. Protocol
    4. 1.4. Text indentation
    5. 1.5. Comments
    6. 1.6. Code linting
  2. 2. HTML style rules
    1. 2.1. Document type
    2. 2.2. Script loading
    3. 2.3. Type attributes
    4. 2.4. ID in Headings
    5. 2.5. Quotation marks
    6. 2.6. 0 values
    7. 2.7. Shorthand Properties
    8. 2.8. Hexadecimal Notation
  3. 3. To be continued
  4. 4. 参考资料
|