1, Naming conventions

Naming conventions commonly used in the market:

• Camel case (small hump Nomenclature - initial lowercase)
• PascalCase (hump Nomenclature - capital letters)
• Kebab case
• Snake (underlined)

1.1 naming of project documents

1.1.1 project name

All in lowercase, separated by dashes. Example: my project name.

1.1.2 directory name

Refer to the project naming rules. If there is a plural structure, the plural naming method shall be adopted. Examples: docs, assets, components, directives, mixins, utils, and views.

my-project-name/
|- BuildScript    // Pipeline deployment file directory
|- docs           // Detailed document directory for the project (optional)
|- nginx          // Front end project nginx agent file directory deployed on container
|- node_modules   // Downloaded dependent packages
|- public         // Static page directory
    |- index.html // Project entrance
|- src            // Source directory
    |- api        // http request directory
    |- assets     // Static resource directory, where the resources will be built by wabpack
        |- icon   // icon storage directory
        |- img    // Picture storage directory
        |- js     // Public js file directory
        |- scss   // Public style scss storage directory
            |- frame.scss   // Entry file
            |- global.scss  // Common style
            |- reset.scss   // reset styles 
    |- components     // assembly
    |- plugins        // plug-in unit
    |- router         // route
    |- routes         // Detailed route splitting directory (optional)
        |- index.js
    |- store          // Global state management
    |- utils          // Tool storage directory
        |- request.js // Public request tool
    |- views          // Page storage directory
    |- App.vue        // Root component
    |- main.js        // Entry file
    |- tests          // test case
    |- .browserslistrc// Browser compatibility profile
    |- .editorconfig  // Editor profile
    |- .eslintignore  // eslint ignore rule
    |- .eslintrc.js   // eslint rule
    |- .gitignore     // git ignore rule
    |- babel.config.js // babel rule
    |- Dockerfile // Docker deployment file
    |- jest.config.js
    |- package-lock.json
    |- package.json // rely on
    |- README.md // Project README
    |- vue.config.js // webpack configuration
 Copy code

1.1.3 image file name

All are in lowercase. Single word naming is preferred, and multiple word names are separated by underline.

banner_sina.gif
menu_aboutus.gif
menutitle_news.gif
logo_police.gif
logo_national.gif
pic_people.jpg
pic_TV.jpg
 Copy code

1.1.4 HTML file name

All are in lowercase. Single word naming is preferred, and multiple word names are separated by underline.

|- error_report.html
|- success_report.html
 Copy code

1.1.5 CSS file name

All are in lowercase. Single word naming is preferred, and multiple word names are separated by a dash.

|- normalize.less
|- base.less
|- date-picker.scss
|- input-number.scss
 Copy code

1.1.6 JavaScript file name

All are in lowercase. Single word naming is preferred, and multiple word names are separated by a dash.

|- index.js
|- plugin.js
|- util.js
|- date-util.js
|- account-model.js
|- collapse-transition.js
 Copy code

The above rules can be quickly remembered as "static file underline, compiled file dashes".

1.2 Vue component naming

1.2.1 single file component name

Single file components with a file extension of. vue. Single file component names should always start with uppercase words (PascalCase).

components/
|- MyComponent.vue
 Copy code

1.2.2 single instance component name

Components with only a single active instance should be named with The prefix to show their uniqueness.

This does not mean that the component can only be used for a single page, but_ Each page_ Use only once. These components will never accept any props because they are customized for your application. If you find it necessary to add prop, it indicates that it is actually a reusable component_ Just now_ Use only once per page.

For example, the header and sidebar components are used in almost every page and do not accept prop. This component is specially customized for the application.

components/
|- TheHeading.vue
|- TheSidebar.vue
 Copy code

1.2.3 basic component name

Basic components: basic components that do not contain business, independent and specific functions, such as date selector, modal box, etc. As the basic control of the project, such components will be widely used. Therefore, the API of components is abstracted too much, and different functions can be realized through different configurations.

The basic components that apply specific styles and conventions (that is, the components that display classes, are illogical or stateless, and are not doped with business logic) should all begin with a specific prefix - Base. Basic components can be used multiple times in one page and can be reused in different pages. They are highly reusable components.

components/
|- BaseButton.vue
|- BaseTable.vue
|- BaseIcon.vue
 Copy code

1.2.4 business components

Business component: unlike the basic component, which only contains a function, it is reused by multiple pages in the business (with reusability). The difference between it and the basic component is that the business component will only be used in the current project, not universal, and will contain some businesses, such as data requests; The basic component contains no business and can be used in any project. It has a single function, such as an input box with data verification function.

Components doped with complex business (with their own data and prop related processing) that is, business components should be named with the prefix Custom. A business component is in a page. For example, there is a card list in a page, and the card whose style and logic are closely related to the business is a business component.

components/
|- CustomCard.vue
 Copy code

1.2.5 tightly coupled component name

Child components closely coupled with the parent component should be named with the parent component name as a prefix. Because editors usually organize files alphabetically, this can put the associated files together.

components/
|- TodoList.vue
|- TodoListItem.vue
|- TodoListItemButton.vue
 Copy code

1.2.6 word order in component name

Component names should start with high-level (usually general) words and end with descriptive modifiers. Because editors usually organize files alphabetically, the important relationships between components are now clear. The following components are mainly used for search and setting functions.

components/
|- SearchButtonClear.vue
|- SearchButtonRun.vue
|- SearchInputQuery.vue
|- SearchInputExcludeGlob.vue
|- SettingsCheckboxTerms.vue
|- SettingsCheckboxLaunchOnStartup.vue
 Copy code

There is another multi-level directory method. Put all search components in the "search" directory and all setting components in the "settings" directory. We only recommend doing this in very large applications (such as 100 + components), because it takes more effort to find between multi-level directories than to scroll through a single component directory.

1.2.7 component name of complete word

Component names should be preferred to abbreviations. Automatic completion in the editor has made the cost of writing long names very low, but the clarity it brings is very valuable. In particular, infrequently used abbreviations should be avoided.

components/
|- StudentDashboardSettings.vue
|- UserProfileOptions.vue
 Copy code

1.3 code parameter naming

1.3.1 name

The component name should always be multiple words and should always be PascalCase. Except for the root component App and Vue built-in components such as < transition >, < component >. This avoids conflicts with existing and future HTML elements, because all HTML element names are single words.

export default {
  name: 'ToDoList',
  // ...
}
Copy code

1.3.2 prop

When declaring prop, its name should always use camelCase, while kebab case should always be used in templates and JSX. We simply follow the conventions of each language. In JavaScript, camelCase is more natural. In HTML, it is kebab case.

<WelcomeMessage greeting-text="hi"/>
Copy code

export default {
  name: 'MyComponent',
  // ...
  props: {
    greetingText: {
      type: String,
      required: true,
      validator: function (value) {
        return ['syncing', 'synced',].indexOf(value) !== -1
      }
    }
  }
}
Copy code

1.3.3 router

Vue Router Path is named in kebab case format. Words using Snake (such as: / user_info) or camelCase (such as: / userInfo) will be regarded as a word, and search engines cannot distinguish semantics.

// bad
{
  path: '/user_info', // user_info as a word
  name: 'UserInfo',
  component: UserInfo,
  meta: {
    title: ' - user',
    desc: ''
  }
},

// good
{
  path: '/user-info', // Can be parsed into user info
  name: 'UserInfo',
  component: UserInfo,
  meta: {
    title: ' - user',
    desc: ''
  }
},
Copy code

1.3.4 components in formwork

For most projects, the component name should always be Pascal case in single file components and string templates, but always kebab case in DOM templates.

<!-- In single file components and string templates --> 
<MyComponent/>

<!-- stay DOM In template --> 
<my-component></my-component>
Copy code

1.3.5 self closing assembly

Components without content in single file components, string templates, and JSX should be self closing -- but never in DOM templates.

<!-- In single file components and string templates -->
<MyComponent/>

<!-- Everywhere -->
<my-component></my-component>
Copy code

1.3.6 variables

• Naming method: camelCase
• Naming convention: type + method of object description or attribute

// bad
var getTitle = "LoginTable"

// good
let tableTitle = "LoginTable"
let mySchool = "My school"
Copy code

1.3.7 constants

• Naming method: all uppercase underline split
• Naming convention: use capital letters and underscores to combine names, and underscores are used to divide words

const MAX_COUNT = 10
const URL = 'http://test.host.com'
Copy code

1.3.8 method

• Naming method: camelCase
• Naming standard: use verb or verb + noun form uniformly

// 1. In general, use the verb + noun form
// bad
go,nextPage,show,open,login

// good
jumpPage,openCarInfoDialog

// 2. Request data method, ending with data
// bad
takeData,confirmData,getList,postForm

// good
getListData,postFormData

// 3. Single verb situation
init,refresh
 Copy code

1.3.9 user defined events

Custom events should always use the event name of kebab case.

Unlike components and prop s, there is no automatic case conversion for event names. Instead, the triggered event name needs to exactly match the name used to listen to this event.

this.$emit('my-event')
Copy code

<MyComponent @my-event="handleDoSomething" />
Copy code

Unlike components and props, event names are not used as JavaScript variable names or property names, so there is no reason to use camelCase or PascalCase. In addition, the v-on event listener will be automatically converted to all lowercase in the DOM template (because HTML is case insensitive), so v-on:myevent will become v-on:myevent - making it impossible for myEvent to be monitored.

• Native event reference list [1]

It can be found from the native event that its usage is as follows:

<div
  @blur="toggleHeaderFocus"
  @focus="toggleHeaderFocus"
  @click="toggleMenu"
  @keydown.esc="handleKeydown"
  @keydown.enter="handleKeydown"
  @keydown.up.prevent="handleKeydown"
  @keydown.down.prevent="handleKeydown"
  @keydown.tab="handleKeydown"
  @keydown.delete="handleKeydown"
  @mouseenter="hasMouseHoverHead = true"
  @mouseleave="hasMouseHoverHead = false">
</div>
Copy code

And to distinguish_ Native event_ And_ Custom event_ For the use in Vue, it is suggested that in addition to using kebab case for multi word event names, the naming should also follow the form of on + verb, as follows:

<!-- Parent component -->
<div
  @on-search="handleSearch"
  @on-clear="handleClear"
  @on-clickoutside="handleClickOutside">
</div>
Copy code

// Subcomponents
export default {
  methods: {
    handleTriggerItem () {
      this.$emit('on-clear')
    }
  }
}
Copy code

1.3.10 event method

• Naming method: camelCase
• Naming convention: handle + name (optional) + verb

<template>
  <div
    @click.native.stop="handleItemClick()"
    @mouseenter.native.stop="handleItemHover()">
  </div>
</template>

<script>

export default {
  methods: {
    handleItemClick () {
      //...
    },
    handleItemHover () {
      //...
    }
  }
}
</script>
Copy code

2, Code specification

2.1 Vue

2.1.1 code structure

<template>
  <div id="my-component">
    <DemoComponent />
  </div>
</template>

<script>
import DemoComponent from '../components/DemoComponent'

export default {
  name: 'MyComponent',
  components: {
    DemoComponent
  },
  mixins: [],
  props: {},
  data () {
    return {}
  },
  computed: {},
  watch: {}
  created () {},
  mounted () {},
  destroyed () {},
  methods: {},
}
</script>

<style lang="scss" scoped>
#my-component {
}
</style>
Copy code

2.1.2 data

The data of the component must be a function.

// In a .vue file
export default {
  data () {
    return {
      foo: 'bar'
    }
  }
}
Copy code

2.1.3 prop

Prop definitions should be as detailed as possible.

export default {
  props: {
    status: {
      type: String,
      required: true,
      validator: function (value) {
        return [
          'syncing', 
          'synced',
          'version-conflict',
          'error'
        ].indexOf(value) !== -1
      }
    }
  }
}
Copy code

2.1.4 computed

Complex computational attributes should be divided into as many simpler attributes as possible. Small, focused computing attributes reduce the hypothetical restrictions on the use of information, so there is no need for so much refactoring when requirements change.

// bad
computed: { 
  price: function () { 
    var basePrice = this.manufactureCost / (1 - this.profitMargin) 
    return ( 
      basePrice - 
      basePrice * (this.discountPercent || 0) 
    ) 
  } 
}

// good
computed: {
  basePrice: function () {
    return this.manufactureCost / (1 - this.profitMargin)
  },
  discount: function () {
    return this.basePrice * (this.discountPercent || 0)
  },
  finalPrice: function () {
    return this.basePrice - this.discount
  }
}
Copy code

2.1.5 setting key values for v-for

key must be used with v-for on components to maintain the state of internal components and their subtrees. Even maintain predictable behavior on elements, such as object constancy in animation [2].

<ul>
  <li
    v-for="todo in todos"
    :key="todo.id">
      {{ todo.text }}
  </li>
</ul>
Copy code

2.1.6 v-if and v-for are mutually exclusive

Never use v-if and v-for on the same element at the same time.

<!-- bad: Console error -->
<ul>
  <li
    v-for="user in users"
    v-if="shouldShowUsers"
    :key="user.id">
      {{ user.name }}
  </li>
</ul>
Copy code

We tend to do this in two common situations:

• To filter items in a list (such as v-for="user in users" v-if="user.isActive"). In this case, replace users with a calculated attribute (such as activeUsers) to return the filtered list.

computed: {
  activeUsers: function () {
    return this.users.filter((user) => {
      return user.isActive
    })
  }
}
Copy code

<ul>
  <li
    v-for="user in activeUsers"
    :key="user.id">
      {{ user.name }}
  </li>
</ul>
Copy code

• To avoid rendering lists that should have been hidden (such as v-for="user in users" v-if="shouldShowUsers"). In this case, move the v-if to the container element (such as ul, ol).

<!-- bad -->
<ul>
  <li
    v-for="user in users"
    v-if="shouldShowUsers"
    :key="user.id">
      {{ user.name }}
  </li>
</ul>

<!-- good -->
<ul v-if="shouldShowUsers">
  <li
    v-for="user in users"
    :key="user.id">
      {{ user.name }}
  </li>
</ul>
Copy code

2.1.7 elements of multiple attribute s

The elements of multiple attributes should be written in multiple lines, one line for each attribute.

<!-- bad -->
<img src="https://vuejs.org/images/logo.png" alt="Vue Logo">
<MyComponent foo="a" bar="b" baz="c"/>
Copy code

<!-- good -->
<img
  src="https://vuejs.org/images/logo.png"
  alt="Vue Logo">

<MyComponent
  foo="a"
  bar="b"
  baz="c"/>
Copy code

2.1.8 simple expressions in templates

The component template should contain only simple expressions, and complex expressions should be refactored into calculated properties or methods.

Complex expressions can make your template less explicit. We should try to describe what should happen, not how to calculate that value. Moreover, computing properties and methods make the code reusable.

// bad
{{
  fullName.split(' ').map((word) => {
    return word[0].toUpperCase() + word.slice(1)
  }).join(' ')
}}
Copy code

Better practices:

<!-- In template -->
{{ normalizedFullName }}
Copy code

// Complex expression has been moved into a calculated property
computed: {
  normalizedFullName: function () {
    return this.fullName.split(' ').map(function (word) {
      return word[0].toUpperCase() + word.slice(1)
    }).join(' ')
  }
}
Copy code

2.1.9 quoted attribute value

Non empty HTML attribute values should always be enclosed in double quotes.

<!-- bad -->
<input type=text>
<AppSidebar :style={width:sidebarWidth+'px'}>
Copy code

<!-- good -->
<input type="text">
<AppSidebar :style="{ width: sidebarWidth + 'px' }">
Copy code

2.1.10 abbreviations of directives

• Use: to represent v-bind:
• Use @ for v-on:
• Use # to represent v-slot:

<input
  :value="newTodoText"
  :placeholder="newTodoInstructions">

<input
  @input="onInput"
  @focus="onFocus">

<template #header>
  <h1>Here might be a page title</h1>
</template>

<template #footer>
  <p>Here's some contact info</p>
</template>
Copy code

2.2 HTML

2.2.1 document template

HTML5 file template:

<!DOCTYPE html>
  <html lang="zh-CN">
  <head>
    <meta charset="UTF-8">
    <title>HTML5 Standard template</title>
  </head>
  <body>
  </body>
</html>
Copy code

Mobile terminal:

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport"
        content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, shrink-to-fit=no">
    <meta name="format-detection" content="telephone=no">
    <title>Mobile terminal HTML Template</title>

    <!-- S DNS Pre analysis -->
    <link rel="dns-prefetch" href="">
    <!-- E DNS Pre analysis -->

    <!-- S For online style page slice development, please directly cancel the annotation reference -->
    <!-- #include virtual="" -->
    <!-- E Online style page slice -->

    <!-- S Local debugging. Select the debugging mode according to the development mode. Please delete it -->
    <link rel="stylesheet" href="css/index.css">
    <!-- /Local debugging mode -->

    <link rel="stylesheet" href="http://srcPath/index.css">
    <!-- /Development machine debugging mode -->
    <!-- E Local debugging -->

</head>
<body>
</body>
</html>
Copy code

PC end:

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="keywords" content="your keywords">
    <meta name="description" content="your description">
    <meta name="author" content="author,email address">
    <meta name="robots" content="index,follow">
    <meta http-equiv="X-UA-Compatible" content="IE=Edge,chrome=1">
    <meta name="renderer" content="ie-stand">
    <title>PC end HTML Template</title>

    <!-- S DNS Pre analysis -->
    <link rel="dns-prefetch" href="">
    <!-- E DNS Pre analysis -->

    <!-- S For online style page slice development, please directly cancel the annotation reference -->
    <!-- #include virtual="" -->
    <!-- E Online style page slice -->

    <!-- S Local debugging. Select the debugging mode according to the development mode. Please delete it -->
    <link rel="stylesheet" href="css/index.css">
    <!-- /Local debugging mode -->

    <link rel="stylesheet" href="http://srcPath/index.css">
    <!-- /Development machine debugging mode -->
    <!-- E Local debugging -->
</head>
<body>
</body>
</html>
Copy code

2.2.2 closure of elements and labels

There are five types of HTML elements:

• Empty elements: area, base, br, col, command, embed ded, hr, img, input, keygen, link, meta, param, source, track, wbr
• Original text elements: script, style
• RCDATA elements: textarea, title
• Foreign elements: elements from MathML namespace and SVG namespace
• Regular elements: other elements allowed by HTML are called regular elements

In order to enable the browser to better parse the code and make the code more readable, there are the following conventions:

• All elements with start and end labels shall be written with start and end labels, and some elements that allow the omission of start labels or bundle labels shall also be written.
• Empty element labels are not marked with "/".

<!-- good -->
<div>
    <h1>I am h1 title</h1>
    <p>I am a text, I have a beginning and an end, and the browser can interpret it correctly</p>
</div>
 
<br data-tomark-pass>

<!-- bad -->
<div>
    <h1>I am h1 title</h1>
    <p>I am a text, I have a beginning but no end, and the browser can interpret it correctly
</div>

<br/>
Copy code

2.2.3 code nesting

Element nesting specification, each block element has an independent line, and inline elements are optional.

<!-- good -->
<div>
    <h1></h1>
    <p></p>
</div> 
<p><span></span><span></span></p>

<!-- bad -->
<div>
    <h1></h1><p></p>
</div> 
<p> 
    <span></span>
    <span></span>
</p>
Copy code

Paragraph and title elements can only nest inline elements.

<!-- good -->
<h1><span></span></h1>
<p><span></span><span></span></p>

<!-- bad -->
<h1><div></div></h1>
<p><div></div><div></div></p>
Copy code

2.3 CSS

2.3.1 style file

The style file must be written with the @ charset rule, and must start writing at the first character of the first line of the style file, with the encoding name of "UTF-8".

• recommend:

@charset "UTF-8";
.jdc {}
Copy code

• Not recommended:

/* @charset Rule does not start with the first character on the first line of the file */
@charset "UTF-8";
.jdc {}

/* @charset The rule is not in lowercase */
@CHARSET "UTF-8";
.jdc {}

/* No @ charset rule */
.jdc {}
Copy code

2.3.2 code formatting

There are generally two types of style writing: one is Compact format and the other is Expanded format.

• Recommended: Expanded format

.jdc {
  display: block;
  width: 50px;
}
Copy code

• Not recommended: Compact format

.jdc { display: block; width: 50px;}
Copy code

2.3.3 code case

Style selectors, attribute names, attribute values and keywords are all written in lowercase letters, and attribute strings are allowed to use case.

• recommend:

.jdc {
  display: block;
}
Copy code

• Not recommended:

.JDC {
  DISPLAY: BLOCK;
}
Copy code

2.3.4 code legibility

1. There is a space between the left parenthesis and the class name, and a space between the colon and the attribute value.

• recommend:

.jdc {
  width: 100%;
}
Copy code

• Not recommended:

.jdc{
  width:100%;
}
Copy code

1. Comma separated values, followed by a space.

• recommend:

.jdc {
  box-shadow: 1px 1px 1px #333, 2px 2px 2px #ccc;
}
Copy code

• Not recommended:

.jdc {
  box-shadow: 1px 1px 1px #333,2px 2px 2px #ccc;
}
Copy code

1. Open a new line for a single CSS selector or new declaration.

• recommend:

.jdc, .jdc_logo, .jdc_hd {
  color: #ff0;
}

.nav{
  color: #fff;
}
Copy code

• Not recommended:

.jdc, .jdc_logo, .jdc_hd {
  color: #ff0;
}.nav{
  color: #fff;
}
Copy code

1. The color value rgb() rgba() hsl() hsla() rect() does not need spaces, and the value should not have unnecessary 0.

• recommend:

.jdc {
  color: rgba(255,255,255,.5);
}
Copy code

• Not recommended:

.jdc {
  color: rgba( 255, 255, 255, 0.5 );
}
Copy code

1. If the hexadecimal value of the attribute value can be abbreviated, use abbreviated as far as possible.

• recommend:

.jdc {
  color: #fff;
}
Copy code

• Not recommended:

.jdc {
  color: #ffffff;
}
Copy code

1. Do not specify units for 0.

• recommend:

.jdc {
  margin: 0 10px;
}
Copy code

• Not recommended:

.jdc {
  margin: 0px 10px;
}
Copy code

2.3.5 attribute value quotation marks

When quotation marks are required for CSS attribute values, single quotation marks shall be used uniformly.

• recommend:

.jdc {
  font-family: 'Hiragino Sans GB';
}
Copy code

• Not recommended:

.jdc {
  font-family: "Hiragino Sans GB";
}
Copy code

2.3.6 attribute writing suggestions

The following sequence is recommended:

1. Layout location attribute: display / position / float / clear / visibility / overflow
2. Self attribute: width / height / margin / padding / border / background
3. Text attribute: color / font / text decoration / text align / vertical align / white space / break word
4. Other attributes (CSS3): content / cursor / border radius / box shadow / text shadow / background: linear gradient

.jdc {
  display: block;
  position: relative;
  float: left;
  width: 100px;
  height: 100px;
  margin: 0 10px;
  padding: 20px 0;
  font-family: Arial, 'Helvetica Neue', Helvetica, sans-serif;
  color: #333;
  background: rgba(0,0,0,.5);
  -webkit-border-radius: 10px;
  -moz-border-radius: 10px;
  -o-border-radius: 10px;
  -ms-border-radius: 10px;
  border-radius: 10px;
}
Copy code

3.3.7 CSS3 browser private prefix

CSS3 browser private prefix comes first and standard prefix comes last.

.jdc {
  -webkit-border-radius: 10px;
  -moz-border-radius: 10px;
  -o-border-radius: 10px;
  -ms-border-radius: 10px;
  border-radius: 10px;
}
Copy code

2.4 JavaScript

2.4.1 single line code block

Use spaces in single line blocks.

• Not recommended:

function foo () {return true}
if (foo) {bar = 0}
Copy code

• recommend:

function foo () { return true }
if (foo) { bar = 0 }
Copy code

2.4.2 brace style

In the process of programming, curly braces style is closely related to indentation style. There are many methods to describe the position of curly braces relative to code blocks. In JavaScript, there are three main styles, as follows:

• [recommended] One True Brace Style

if (foo) {
  bar()
} else {
  baz()
}
Copy code

• Stroustrup

if (foo) {
  bar()
}
else {
  baz()
}
Copy code

• Allman

if (foo)
{
  bar()
}
else
{
  baz()
}
Copy code

2.4.3 spaces in code

1. Spaces before and after commas can improve the readability of the code. The team agreed to use spaces after commas and no spaces before commas.

• recommend:

var foo = 1, bar = 2
 Copy code

• Not recommended:

var foo = 1,bar = 2

var foo = 1 , bar = 2

var foo = 1 ,bar = 2
 Copy code

1. There cannot be a space between the key and value of an object literal, and a space is required between the colon and value of an object literal.

• recommend:

var obj = { 'foo': 'haha' }
Copy code

• Not recommended:

var obj = { 'foo' : 'haha' }
Copy code

1. Add a space before the code block.

• recommend:

if (a) {
  b()
}

function a () {}
Copy code

• Not recommended:

if (a){
  b()
}

function a (){}
Copy code

1. A space should be added before the parentheses of a function declaration.

• recommend:

function func (x) {
  // ...
}
Copy code

• Not recommended:

function func(x) {
  // ...
}
Copy code

1. Spaces are prohibited in function calls.

• recommend:

fn()
Copy code

• Not recommended:

fn ()

fn
()
Copy code

1. You need to add spaces before and after the operator.

• recommend:

var sum = 1 + 2
 Copy code

• Not recommended:

var sum = 1+2
 Copy code

3, Annotation specification

Purpose of note:

• Improve the readability of the code, so as to improve the maintainability of the code

Principles of notes:

• As short as possible if not necessary
• As long as necessary

3.1 HTML file comments

3.1.1 single line notes

It is generally used for simple descriptions, such as some state descriptions, attribute descriptions, etc.

There is a space character before and after the comment content. The comment is located above the code to be commented and occupies a separate line.

• recommend:

<!-- Comment Text -->
<div>...</div>
Copy code

• Not recommended

<div>...</div><!-- Comment Text -->

<div><!-- Comment Text -->
  ...
</div>
Copy code

3.1.2 module notes

It is generally used to describe the name of the module and the position where the module starts and ends.

One space character before and after the comment content, <-- S comment text \ -- > indicates that the module starts, <-- E comment text \ -- > indicates the end of the module, with one line between modules.

• recommend:

<!-- S Comment Text A --> 
<div class="mod_a">
  ...
</div>
<!-- E Comment Text A -->
 
<!-- S Comment Text B --> 
<div class="mod_b">
  ...
</div>
<!-- E Comment Text B -->
Copy code

• Not recommended

<!-- S Comment Text A -->
<div class="mod_a">
  ...
</div>
<!-- E Comment Text A -->
<!-- S Comment Text B --> 
<div class="mod_b">
  ...
</div>
<!-- E Comment Text B -->
Copy code

3.1.3 nested module notes

When module comments appear again in the module comments, nested modules are no longer used in order to highlight the main modules.

<!-- S Comment Text -->
<!-- E Comment Text -->
Copy code

Instead, use

<!-- /Comment Text -->
Copy code

Comments are written on a separate line at the bottom of the tag at the end of the module.

<!-- S Comment Text A -->
<div class="mod_a">
  
    <div class="mod_b">
        ...
    </div>
    <!-- /mod_b -->
     
    <div class="mod_c">
     ...
    </div>
    <!-- /mod_c -->
  
</div>
<!-- E Comment Text A -->
Copy code

3.2 CSS file comments

3.2.1 single line notes

The first character and the last character of the comment content are a space character, which occupy a separate line, separated by a line.

• recommend:

/* Comment Text */ 
.jdc {} 

/* Comment Text */ 
.jdc {}
Copy code

• Not recommended:

/*Comment Text*/
.jdc {
  display: block;
}

.jdc {
  display: block;/*Comment Text*/
}
Copy code

3.2.2 module notes

The first character and the last character of the comment content are a space character, / * and module information description occupy one line, multiple horizontal separators - and * / occupy one line, and there are two lines between lines.

• recommend:

/* Module A
---------------------------------------------------------------- */
.mod_a {}


/* Module B
---------------------------------------------------------------- */
.mod_b {}
Copy code

• Not recommended:

/* Module A ---------------------------------------------------- */
.mod_a {}
/* Module B ---------------------------------------------------- */
.mod_b {}
Copy code

3.2.3 document notes

Note the page name, author, creation date and other information under the style file encoding declaration @ charset statement.

@charset "UTF-8";
/**
 * @desc File Info
 * @author Author Name
 * @date 2015-10-10
 */
Copy code

3.3 JavaScript file comments

3.3.1 single line notes

Single line comments use / /. Comments should be written on a separate line above the annotated object and should not be appended to a statement.

• recommend:

// is current tab
const active = true
 Copy code

• Not recommended:

const active = true // is current tab
 Copy code

An empty line is required above the comment line (unless the top of a block is above the comment line) to increase readability.

• recommend:

function getType () {  
  console.log('fetching type...')
  
  // set the default type to 'no type'
  const type = this.type || 'no type'
  return type
}
Copy code

// A blank line is not required when the top of a block is above the comment line
function getType () {  
  // set the default type to 'no type'
  const type = this.type || 'no type'   
  return type
}
Copy code

• Not recommended:

function getType () {  
  console.log('fetching type...')
  // set the default type to 'no type'
  const type = this.type || 'no type'
  return type
}
Copy code

3.3.2 multiline notes

Multiline comments use / * *... * /, not multiline / /.

• recommend:

/**
 * make() returns a new element
 * based on the passed-in tag name
 */
function make (tag) {
  // ...

  return element
}
Copy code

• Not recommended:

// make() returns a new element
// based on the passed in tag name
function make (tag) {
  // ...

  return element
}
Copy code

3.3.3 comment space

A space is required between the comment content and the comment character to increase readability. eslint: spaced-comment.

• recommend:

// is current tab
const active = true

/**
 * make() returns a new element
 * based on the passed-in tag name
 */
function make(tag) {  
  // ...

  return element
}
Copy code

• Not recommended:

//is current tab
const active = true

/**
 *make() returns a new element
 *based on the passed-in tag name
 */
function make(tag) {  
  // ...

  return element
}
Copy code

3.3.4 special marks

Sometimes we find a possible bug, but it can't be fixed for some reasons; Or there are some functions to be completed in a certain place. At this time, we need to use the corresponding special tag comments to inform ourselves or partners in the future. There are two common special marks:

• //FIXME: explain what the problem is
  • //TODO: explain what else to do or the solution to the problem

class Calculator extends Abacus {
  constructor () {
    super ()

      // FIXME: shouldn't use a global here
      total = 0

      // TODO: total should be configurable by an options param
      this.total = 0
  }
}
Copy code

3.3.5 document notes

Document annotations, such as functions, classes, files, events, etc; All use the jsdoc specification.

/**
 * Book Class, representing a book
 * @constructor
 * @param {string} title - The title of a book
 * @param {string} author - The author of a book
 */
function Book (title, author) {
  this.title = title
  this.author = author
}

Book.prototype = {
  /**
   * Get the title of the book
   * @returns {string|*}
   */
  getTitle: function () {
    return this.title
  },
  /**
   * Set the number of pages in the book
   * @param pageNum {number} the number of pages
   */
  setPageNum: function (pageNum) {
    this.pageNum=pageNum
  }
}
Copy code

3.3.6 annotation tools

ESLint is the most popular JS code checking tool at present. There are some annotation related rules in ESLint, which users can choose to open:

• valid-jsdoc
• require-jsdoc
• no-warning-comments
• capitalized-comments
• line-comment-position
• lines-around-comment
• multiline-comment-style
• no-inline-comments
• spaced-comment

4, Others

• Use two spaces to indent and wrap lines.
• It is recommended to add a semicolon at the end of JavaScript code for large team multi person collaborative projects.
• Small individual innovation and hand training projects can try to use the style without semicolon at the end of JavaScript code, which is more refreshing and concise.