2016-09-09

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:

my-script.js
my-camel-case-name.css
i-love-underscores.html
my-script.js

For readability purpose. Users may mistake the underscores for spaces, as the underlining in the link hides the underscores;

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)

Makes the URL relative—prevents mixed content issues;

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:

<ul>
    <li>Fantastic</li>
    <li>Great</li>
    <li>
        <a href="#">Test</a>
    </li>
</ul>

Make code appearing identical across platforms;

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.

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:

<html>
    <head>
        <link rel="stylesheet" href="main.css">
    </head>
    <body>
        <!-- body goes here -->
        <script src="main.js" async></script>
    </body>
</html>

On modern browsers, this will asynchronously load the script and don’t wait for CSSOM to complete before loading;

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>

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;

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

参考资料

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
Isobar Front-end Code Standards by Isobar on 2015/8/25: http://isobar-idev.github.io/code-standards/
[译文] Isobar 前端代码规范及最佳实践 by 老码农 on 2015/8/25: http://coderlmn.github.io/code-standards/