Front-end JS project development specification

The purpose of a specification is to write high-quality code that makes your team members happy every day and happy to be around.

From the opening paragraph of the Statute of Ali:

—- The complexity of modern software architectures requires collaborative development. How to collaborate effectively? For example, the formulation of traffic laws and regulations is ostensibly to limit the right to drive, but in fact to protect the personal safety of the public. Just imagine that if there is no speed limit and no traffic lights, no one will dare to drive on the road. For software, proper specifications and standards do not eliminate the creativity and elegance of code content, but limit excessive personalization, work together in a universally recognized and unified way, improve collaboration efficiency and reduce communication costs. Between the lines of the code flowing is the blood of the software system, the improvement of quality is as little as possible to step on the pit, put an end to the repeated pit, effectively improve the stability of the system, code out of quality.

1. Programming protocol

(1) Naming conventions

1.1.1 Project Naming

Use lowercase characters and delimit by hyphens.

Is exemple: mall – management – system

Counter example: mall_management-system/mallManagementSystem

1.1.2 Directory Naming

All use lowercase way, separated by the hyphen, plural structure, to use plural nomenclature, abbreviations do not use plural

Scripts/styles/components/images/utils/layouts/demo-styles/demo-scripts/img/doc

Counterexample: script/style/demo_scripts/demoStyles/imgs/docs

[special] Directory of components in VUE’s project, named kebab-case

Example: head-search/page-loading/authorized/notice-icon

Counterexample: HeadSearch/PageLoading

[special] All directories in VUE project except components directory also use kebab-case example: page-one/shopping-car/user-management

Counter example: ShoppingCar/UserManagement

1.1.3 Naming JS, CSS, SCSS, HTML, PNG files

Use lowercase characters and delimit by hyphens

Example: render-dom.js/signup. CSS/index.html/company-logo.png

Counterexample: renderdom.js/usermanagement-html

1.1.4 Naming rigor

The naming of the code is strictly forbidden to use pinyin and English mixed way, let alone direct use of Chinese way. Explanation: Correct English spelling and grammar make it easy for readers to understand and avoid ambiguity. Note that even pure pinyin naming should be avoided

Example: Henan/Royalty/RMB and other international common names can be regarded as English.

Counterexample: DaZhePromotion [discount] / getPingfenByName() [score] / int some variable = 3

Eliminate completely non-standard abbreviations and avoid looking at the text without meaning:

Counterexample: AbstractClass “abbreviated” to AbsClass; Condition is “abbreviated” to condi, and such arbitrary abbreviations seriously reduce the legibility of the code.

(2)HTML specification (Vue Template also applies)

1.2.1 HTML type

HTML5 document type declaration is recommended:. (Text/HTML HTML is recommended. Avoid using XHTML. XHTML and its attributes, such as Application/XHTML + XML, have limited support and optimization in browsers.

  • Specified character encoding

  • IE Compatible Mode

  • Specified character encoding

  • Doctype capitalized

Is:

<! DOCTYPE html> <html> <head> <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> <meta charset="UTF-8" /> <title>Page  title</title> </head> <body> <img src="images/company-logo.png" alt="Company" /> </body> </html>Copy the code

1.2.2 the indentation

Indent using 2 Spaces (one TAB)

Nested nodes should be indented.

1.2.3 Block comments

After each block element, list element, and table element, add a pair of HTML comments. The annotation format

<header> <div class="container"> <a href="#"> <! <img SRC ="images/header. JPG "/> </a> </div> </header> <! -- header end --> </body>Copy the code

1.2.4 Semantic Labels

There are a lot of new semantic tags in HTML5, so use semantic tags first and avoid a page full of div or P tags

Is case

<header></header>
<footer></footer>
Copy the code

counter-examples

<div>
  <p></p>
</div>
Copy the code

1.2.5 quotes

Use double quotes (” “) instead of single quotes (” “).

Is exemple: ` `

Example: ` `

(3) CSS specifications

1.3.1 named

  • Class names are lowercase letters separated by hyphens

  • The ID is named in camel shape

  • Variables, functions, mixers, placeholder in SCSS are named in camel shape

The names of ids and classes always use names that reflect the purpose and use of elements, or other generic names, instead of superficial and obscure names

Is not recommended:

.fw-800 {
  font-weight: 800;
}

.red {
  color: red;
}
Copy the code

Recommendation:

.heavy {
  font-weight: 800;
}

.important {
  color: red;
}
Copy the code

1.3.2 selector

1) AVOID using tag names in CSS selectors From the structure, performance, behavior of the principle of separation, should try to avoid HTML tags in CSS, and there will be potential problems in CSS selectors tag names.

2) Many front-end developers write selector chains without direct child selectors (note: the difference between direct child selectors and descendant selectors). Sometimes, this can lead to painful design issues and sometimes it can be very performance draining. However, in any case, this is a very bad practice. If you’re not writing generic selectors that need to match to the end of the DOM, you should always consider direct child selectors.

Is not recommended:

.content .title {
  font-size: 2rem;
}
Copy the code

Recommendation:

.content > .title {
  font-size: 2rem;
}
Copy the code

1.3.3 Use abbreviated attributes whenever possible

Is not recommended:

border-top-style: none; font-family: palatino, georgia, serif; font-size: 100%; The line - height: 1.6; padding-bottom: 2em; padding-left: 1em; padding-right: 1em; padding-top: 0;Copy the code

Recommendation:

border-top: 0;
font: 100%/1.6 palatino, georgia, serif;
padding: 0 1em 2em;
Copy the code

1.3.4 Each selector and attribute has an exclusive row

Is not recommended:

button{ width:100px; height:50px; color:#fff; background:#00a0e9; }Copy the code

Recommendation:

button{
  width:100px;
  height:50px;
  color:#fff;
  background:#00a0e9;
}
Copy the code

1.3.5 Omits units after 0

Is not recommended:

div{
  padding-bottom: 0px;
  margin: 0em;
}
Copy the code

Recommendation:

div{
  padding-bottom: 0;
  margin: 0;
}
Copy the code

1.3.6 Avoid ID and global label selectors to prevent contamination of global styles

Is not recommended:

#header{
  padding-bottom: 0px;
  margin: 0em;
}
Copy the code

Recommendation:

.header{
  padding-bottom: 0px;
  margin: 0em;
}
Copy the code

(4) LESS specification

1.4.1 Code organization

1) Place the public less files in the style/less/common folder

Example: / / color. Less common. Less

2) Organize in the following order

1, @ import; 2. Variable declaration; 3. Style declarations;

@import "mixins/size.less";

@default-text-color: #333;

.page {
  width: 960px;
  margin: 0 auto;
}
Copy the code

1.4.2 Avoid excessive nesting levels

Limit the nesting depth to 3 levels. For nesting beyond 4 levels, re-evaluation is given. This avoids overly verbose CSS selectors. Avoid lots of nested rules. Interrupt when readability is affected. It is recommended to avoid nesting rules with more than 20 lines

Is not recommended:

.main{
  .title{
    .name{
       color:#fff
    }
  }
}
Copy the code

Recommendation:

.main-title{
   .name{
      color:#fff
   }
}
Copy the code

(v) Javascript specifications

1.5.1 named

1) Name lowerCamelCase with a lower camel hump. The names in the code must not end with an underscore or a dollar sign

Example: _name/name_ / name$

2) Method names, parameter names, member variables and local variables all use the lowerCamelCase style and must follow the hump form.

Example: localValue/getHttpMessage()/inputUserId

The method name must be a verb or verb + noun

Example: saveShopCarData /openShopCarInfoDialog

Counter example: save/open/show/go

*** hereby indicates that the following five words are used for details of addition, deletion, review and modification, and other words are not allowed to be used (for the purpose of unifying all ends) *** 
add / update / delete / detail / get
Copy the code

Function methods:

Get get /set Settings, add add /remove delete create create /destory Remove start Start /stop Stop Open Open /close Close, Read Read /write Write Load load /save save create create /destroy destroy begin Start end backup backup /restore restore Import import /export Export Split /merge inject /extract, attach /detach /separate, view /browse edit /modify Select select /mark copy copy /paste paste undo undo /redo redo insert insert /delete remove add add /append add clean clean /clear Clear, Increase /decrease play play play launch /pause launch compile compile execute Debug debug /trace trace observe /listen Build /publish input /output Encode /decode Encrypt /decrypt compress /decompress Pack Pack /unpack Parse /emit generate connect /disconnect/send /receive Download /upload Update /revert/lock /unlock check out /check in Submit /commit push /pull expand /collapse begin /end, start /finish Enter /exit Abort discard /quit Leave obsolete /depreciate discard, collect /aggregateCopy the code
3) Constant names are all capitalized, words are separated by underscores, and semantic expression is complete and clear, not too long name.

Is exemple: MAX_STOCK_COUNT

Example: MAX_COUNT

1.5.2 Code Format

1) Indent with 2 Spaces

Is:

if (x < y) {
  x += 10;
} else {
  x += 1;
}
Copy the code
2) Insert an empty line to separate the code with different logic, semantics and business to improve readability.

Note: In any case, there is no need to insert more than one blank line for separation.

1.5.3 string

Use single quotation marks (‘) instead of double quotation marks (‘). This is great for creating HTML strings:

Is:

let str = 'foo';
let testDiv = '<div id="test"></div>';
Copy the code

Example:

let str = 'foo';
let testDiv = "<div id='test'></div>";
Copy the code

1.5.4 Object Declaration

1) Create objects with literals

Let user = {};

Example: let user = new Object();

2) Use literals instead of object constructors

Is:

var user = {
  age: 0,
  name: 1,
  city: 3
};
Copy the code

Example:

var user = new Object();
user.age = 0;
user.name = 0;
user.city = 0;
Copy the code

1.5.5 use ES6, 7

The syntax sugars and functions added in ES6,7 must be used in preference. This will simplify your program and make your code more flexible and reusable.

ES6, ES7 new syntax must be enforced, such as arrow functions, await/async, deconstruction, let, for… Of, etc.

1.5.6 brackets

Braces must follow the following keywords (even if the block is only one line) : if, else, for, while, do, switch, try, catch, finally, with.

Is:

if (condition) {
  doSomething();
}
Copy the code

Example:

if (condition) doSomething();
Copy the code

1.5.7 undefined judgment

Never use undefined directly for variable judgments; Use typeof and the string ‘undefined’ to determine variables.

Is:

if (typeof person === 'undefined') {
    ...
}
Copy the code

Example:

if (person === undefined) {
    ...
}
Copy the code

1.5.8 Condition judgment and loop at most three layers

Do not use conditional judgments if you can use trigonometric and logical operators, but remember not to write too long trigonometric operators. If there are more than 3 layers please split the function and write clear comments.

1.5.9 Transformation naming of this

References to the context this can only be named ‘self’

1.5.10 careful with the console. The log

Heavy use of console.log can cause performance problems, so use the log feature with caution in non-Webpack projects

Ii. Vue project specifications

(I) Vue coding basis

Vue project specifications as vUE official specifications (cn.vuejs.org/v2/style-gu…) Is based on the A specification, in which the project development, so all codes comply with the specification.

Please read the official Vue specification carefully, remember, this is the first step.

2.1.1. Component specifications

1) Component names are multiple words.

Component names should always be multiple words (greater than or equal to 2) and named in the KebabCase format. This avoids conflicts with existing and future HTML elements because all HTML element names are single words.

Is:

export default {
  name: 'TodoItem'
  // ...
};
Copy the code

Example:

export default {
  name: 'Todo',
  // ...
}
export default {
  name: 'todo-item',
  // ...
}
Copy the code
2) The component file name is pascal-case format

Is:

components/
|- my-component.vue
Copy the code

Example:

components/
|- myComponent.vue
|- MyComponent.vue
Copy the code
3) Base component file names start with base and use full words instead of abbreviations.

Is:

components/
|- base-button.vue
|- base-table.vue
|- base-icon.vue
Copy the code

Example:

components/
|- MyButton.vue
|- VueTable.vue
|- Icon.vue
Copy the code
4) Child components that are tightly coupled to the parent component should be named prefixed with the parent component name

Is:

Components / | - todo - list. Vue | - todo list - item. Vue | - todo list - item - button. Vue | - user - profile - options. Vue (full word)Copy the code

Example:

The components / | - TodoList. Vue | - TodoItem. Vue | - TodoButton. Vue | - UProfOpts. Vue (use)Copy the code
5) When using components in the Template Template, use PascalCase mode and use self-closing components.

Is:

<! -- In single-file components, string templates, and JSX --> <MyComponent />< Row><table :column="data"/></Row>Copy the code

Example:

<my-component /> <row><table :column="data"/></row>
Copy the code
6) The component’s data must be a function

When using the data attribute in a component (anywhere but new Vue), its value must be a function that returns an object. If it is directly an object, the property values of the sub-components will affect each other.

Is:

export default {
  data () {
    return {
      name: 'jack'
    }
  }
}
Copy the code

Example:

export default {
  data: {
    name: 'jack'
  }
}
Copy the code
7) Prop definitions should be as detailed as possible

  • Must use camelCase camel name

  • Type must be specified

  • A comment must be added to indicate its meaning

  • You must add either required or default

  • Validator validation must be added if there is a business need

Is:

{// Component status, used to control component colors Status: {type: String, required: true, validator: function (value) { return [ 'succ', 'info', 'error' ].indexOf(value) ! == -1}}, // userLevel, used to display number of crown userLevel: {type: String, required: true}}Copy the code
8) Set the scope for the component style

Is:

<template> <button class="btn btn-close">X</button> </template> <! <style scoped>. Btn-close {background-color: red; } </style>Copy the code

Example:

<template> <button class="btn btn-close">X</button> </template> <! <style>. Btn-close {background-color: red; } </style>Copy the code
9) If there are many feature elements, you should actively wrap lines.

Is:

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

Example:

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

2.1.2. Use simple expressions in templates

Component templates should contain only simple expressions, and complex expressions should be refactored to evaluate properties or methods. Complex expressions can make your templates less declarative. We should try to describe what should happen, not how to calculate that value. And evaluating properties and methods makes code reusable.

Is:

<template> <p>{{normalizedFullName}}</p> </template> // Complex expressions have been moved into a computed attribute computed: {normalizedFullName: function () { return this.fullName.split(' ').map(function (word) { return word[0].toUpperCase() + word.slice(1) }).join(' ') } }Copy the code

Example:

<template> <p> {{ fullName.split(' ').map(function (word) { return word[0].toUpperCase() + word.slice(1) }).join(' ') }}  </p> </template>Copy the code

2.1.3 Instructions are abbreviated

Directives are recommended to use abbreviations (: for V-bind:, @ for V-on:, and # for v-slot:)

Is:

<input
  @input="onInput"
  @focus="onFocus"
>
Copy the code

Example:

<input
  v-on:input="onInput"
  @focus="onFocus"
>
Copy the code

2.1.4 Keep the label sequence the same

Single-file components should always keep the label order ‘

Is:

<template>... </template> <script>... </script> <style>... </style>Copy the code

Example:

<template>... </template> <style>... </style> <script>... </script>Copy the code

2.1.5 Key must be set for V-for

2.1.6 V-show and V-IF are selected

If you need to switch very frequently when running, use v-show; If conditions rarely change at run time, use V-if.

2.1.7 Internal Structure sequence of Script Labels

Components > props > Data > computed > Watch > filter > hook functions (in their order of execution) > methods

2.1.8 Vue Router Specifications

1) Routing parameters are used for page skipping data transmission

For example, when page A is switched to page B, data from page A needs to be transferred to page B. It is recommended that route parameters be used instead of saving the data to be transferred and retrieving the vuex data from page B, because refreshing the vuex data on page B may cause vuex data loss. Data cannot be displayed on page B.

Is:

let id = ' 123';
this.$router.push({ name: 'userCenter', query: { id: id } });
Copy the code
2) Use the route lazy loading (lazy loading) mechanism
{path: '/uploadAttachment', name: 'uploadAttachment', meta: {title: 'uploadAttachment', Component: () => import('@/view/components/uploadAttachment/index.vue') },Copy the code
3) Naming conventions in the Router

The path and childrenPoints naming conventions use the kebab-case naming conventions. The directory structure of the vue file should be the same as that of the directory and childrenPoints.

The name naming convention uses the KebabCase naming convention and is consistent with the component name! (To keep the keep-alive feature, keep-alive is cached by component name, so the two must be highly consistent.)

Export const reload = [{path: '/reload', name: 'reload', Component: Main, meta: {title: 'dynamic load', icon: 'icon iconfont' }, children: [ { path: '/reload/smart-reload-list', name: 'SmartReloadList', meta: { title: 'SmartReload', childrenPoints: [{title: 'query ', name: 'smart-reload-search'}, {title:' perform reload', name: 'smart-reload-update'}, {title: 'check execution result', name: 'smart-reload-result'}]}, Component: () => import('@/views/reload/smart-reload/smart-reload-list.vue') } ] } ];Copy the code
4) Naming conventions for path in router

In addition to using the Kebab-case naming convention, path must start with a slash (/), even in children. The following example

Objective:

It is often the case that a page has a problem and you need to find the vue file immediately. If the path does not start with/and consists of parent and children, you often need to search the router file several times to find the vue file. If the path starts with /, you can find the corresponding component immediately

{path: '/file', name: 'file', Component: Main, meta: {title:' file service ', icon: 'ios-cloud-upload'}, children: [{path: '/file', name: 'file', Component: Main, meta: {title:' file service ', icon: 'ios-cloud-upload'}, children: [{path: '/file/file-list', name: 'FileList', component: () => import('@/views/file/file-list.vue') }, { path: '/file/file-add', name: 'FileAdd', component: () => import('@/views/file/file-add.vue') }, { path: '/file/file-update', name: 'FileUpdate', component: () => import('@/views/file/file-update.vue') } ] }Copy the code

(2) Vue project directory specification

2.2.1 basis

All names in the VUE project must be consistent with the backend names.

You must use privielege for router, store, API, etc.

2.2.2 Using vuE-CLI Scaffolding

Initialize the project using vuE-CLI3, with the project name following the naming convention above.

2.2.3 Directory Description

Directories are named according to the above naming convention, where components are named with a capital camel, and all directories except components are named with kebab-case.

SRC | - all the API interface API source directory | - static resource assets, images, ICONS, styles, etc. | | - components utility components - config configuration information | - constants constant information, Project all Enum, global constants | - directives such as the custom command | - filters filter, global tools | - datas analog data, temporary storage | - lib external reference plug-in to store and modify the file | - mock simulation interface, Temporary storage | plugins plugin, the global | - the router routing, Unified management | - store vuex, Unified management | - themes custom style theme | - views view directory | | - role role module name | | -- - | - role - the list. The vue role list page | | -- - | - role - the add. Vue Role of new page | | -- - | - role - update. Vue role updates page | | -- - | -- index. Less role module style | | -- - | - components role module common component folder | | - The employee the employee moduleCopy the code
1) API directory

  • File and variable names must be consistent with those of the back end.

  • This directory corresponds to the back-end API interface, according to the back-end one controller and one API JS file. If the project is large, you can create a directory based on the service and keep it consistent with the backend.

  • The method names in the API should be semantically consistent with the backend API urls.

  • Comments are added for each method in the API, consistent with the backend Swagger document.

Is:

Backend URL: Employeecontroller.java

/employee/add
/employee/delete/{id}
/employee/update
Copy the code

Front end: the employee. Js

AddEmployee: (data) => {return postAxios('/employee/add', data)}, // updateEmployee information updateEmployee: (data) => {return postAxios('/employee/update', data)}, // deleteEmployee: (employeeId) => { return postAxios('/employee/delete/' + employeeId) },Copy the code
2) assets directory

Assets are static resources, which store images, styles, ICONS and other static resources. Static resources are named in the kebab-case format

|assets
|-- icons
|-- images
|   |-- background-color.png
|   |-- upload-header.png
|-- styles
Copy the code
3) components directory

This directory should be divided according to components. The directory is named KebabCase and the component naming rule is KebabCase

|components
|-- error-log
|   |-- index.vue
|   |-- index.less
|-- markdown-editor
|   |-- index.vue
|   |-- index.js
|-- kebab-case
Copy the code
4) constants directory

This directory to store the project all constants, if constant use in vue, please use the vue – enum plug-in (www.npmjs.com/package/vue)…

Directory structure:

|constants
|-- index.js
|-- role.js
|-- employee.js
Copy the code

Example: the employee. Js

Export const EMPLOYEE_STATUS = {NORMAL: {value: 1, desc: 'NORMAL'}, DISABLED: {value: 1, desc: 'DISABLED'}, DELETED: {value: 2, desc: 'deleted'}}; Export const EMPLOYEE_ACCOUNT_TYPE = {QQ: {value: 1, desc: 'QQ login '}, WECHAT: {value: 2, desc: 'WECHAT login'}, DINGDING: {value: 3, desc: 'login'}, USERNAME: {value: 4, desc: 'login'}}; export default { EMPLOYEE_STATUS, EMPLOYEE_ACCOUNT_TYPE };Copy the code
5) Router and Store directories

These two directories must be split business, can not be put into a JS file.

The router structure should be consistent according to the views

Store splits different JS files by business

6) views directory

  • The name must be consistent with the backend, router, and API

  • Components use PascalCase rules

    | – views view directory | | – role role module name | | | – role – the list. The vue role list page | | | – role – the add. Vue role new page | | | – role – update. Vue Role updates page | | | — index. Less role module style | | | – components role module common component folder | | | | – role – the header. Vue role head component | | | | – Role – modal. Vue role pop-up components | | – the employee the employee module | | – behaviors – log activity log log module | | – code – the generator code generator module

2.2.4 Remarks

Tidy up where you must add comments

  • Usage instructions for common components

  • The interface JS files in the API directory must be annotated

  • State, mutation, action, etc. in store must be commented

  • Template in the vue file must be commented, or start end if the file is large

  • Vue file methods, each method must be commented

  • Vue file data, very see words to annotate

2.2.5 other

1) Try not to manipulate the DOM manually

Due to the use of vUE framework, we try to use VUE data-driven DOM update in project development, and try not to manually manipulate DOM (unless absolutely necessary), including: adding, deleting, modifying DOM elements, changing styles, adding events, etc.

2) Remove useless code

If you use tools such as Git or SVN, delete unnecessary codes in time, such as debugging console statements and discarded function codes.