1. Project structure specification
1.1 core idea of project structure
- The relevant codes of business function modules are concentrated in one piece, which is convenient to move and delete
- Realize the separation of concerns and facilitate the development, debugging, maintenance, writing, consulting and understanding of code
1.2 project catalogue
├── vue.config.js/ # webpack configuration file; ├── config/ # Common configuration options related to project construction; │ ├── index.js # Master profile │ ├── dev.env.js # Development environment variables │ ├── prod.env.js # Production environment variables │ └── test.env.js # Test environment variables │ ├── src/ │ ├── main.js # The entry file of webpack; │ ├── assets/ # Resources other than shared codes, such as pictures, icons, videos, etc; │ ├── api/ # Network module, such as interface; │ ├── router/ # Routing module │ ├── I18n/ # Internationalization module │ ├── pages/ # Single page │ ├── vuex/ # Shared component status │ ├── components/ # Shared components;; The components stored here should be display components │ │ ├── base/ # Basic components, such as common pop-up components, loading components and prompt components. │ │ ├── common/ # Shared global components, encapsulated navigation bars, bottom components, etc │ │ ├── temp/ # Template components, such as: the same page is encapsulated into a component. │ │ ├── UItemp/ # Some styles of UI components, such as specific buttons, messages, numbers, etc. in the project, can be encapsulated into components. │ ├── common/ # Shared resources, such as commonly used pictures and icons, shared components, modules, styles, constant files, etc; │ │ ├── compatible/ # Compatible modules, such as modules suitable for various interfaces of App and wechat; │ │ ├── extension/ # Extension modules of existing classes, such as modules that extend Array types; │ │ ├── libraries/ # Store their own encapsulated or referenced libraries; │ │ ├── tools/ # Some tools encapsulated by themselves │ │ ├── constant.js # Constant for storing js; │ │ ├── constant.scss # Store constant of scss; │ │ └── ... │ └── app/ # Store project business code; │ ├── App.vue # Root component of app; ├── public/ # Pure static resources, the files in this directory will not be processed by webpack, and this directory will be copied to the output directory; ├── .babelrc # Configuration file of babel ├── .editorconfig # The configuration file of the editor; Parameters such as indent, space and tabulation can be configured; ├── .eslintrc.js # eslint configuration file ├── .eslintignore # Ignore rules for eslint ├── .gitignore # git ignore profile ├── .postcssrc.js # Configuration file of postcss ├── CHAGNELOG.md # Version update change release ├── index.html # HTML template ├── package.json # npm package configuration file, which defines the npm script, dependent package and other information of the project └── README.md # Project information document
2. Naming conventions
2.1 page naming
- Can intuitively feel the role of the current file
- Named after a small hump
│ │ │ ├── login.vue # Login page │ │ │ ├── changePhone.vue # Modify phone number page
2.2 component naming
- Can intuitively feel the purpose of the current component
- Component naming is always multi word, avoiding conflicts with html elements or tags
- Either start with uppercase or always link with a horizontal line (where items start with uppercase)
components/ |- BaseButton.vue |- BaseTable.vue |- BaseIcon.vue
2.3 picture naming
- Picture folders are generally named after pages or modules, such as login/
- Pictures cannot be named arbitrarily, and it is strictly prohibited to use numbers such as 0, 1, etc. to name pictures directly.
- Picture naming can follow: purpose + description, and multiple words are separated by underscores, such as login_icon.png,pwd_icon.png
- 10k the following pictures are recommended to be placed under assets/img (webpack is directly embedded into base64 when packaged)
- Large and infrequently changed pictures are placed under public/img
- It is forbidden to use pictures for the styles written in css
- For international pictures, the suffix is simplified cn, English en and traditional tw
│ ├── assets/ │ │ ├── img/ # picture │ │ │ ├── common/ # Public picture │ │ │ │ ├── default_avatar.png # Default Avatar │ │ │ ├── login/ # Login module │ │ │ │ ├── login1.png # Login module picture │ │ │ │ ├── login_icon-en.png │ │ │ │ ├── login_icon-cn.png │ │ │ │ ├── login_icon-tw.png │ │ │ ├── userInfo/ # Picture of user center module
2.4 CSS naming
- First, name it according to the content, such as NAV and header
- The sub elements in the content use - links, and the names are all lowercase, such as card item
- Modifier class (changeable) uses links, such as card item – warning
- If there is no content, assist with behavior, such as box shader
- It can be abbreviated without affecting semantics, such as img box, BTN
2.4.1 common css naming:
- Header: header
- Content: content/container
- footer
- Navigation: nav
- Sidebar: sidebar
- Column: column
- Page periphery controls the overall layout width: wrapper
- left right center
- Login bar: loginbar
- logo: logo
- Ad: banner
- Page body: main
- hot spots: hot
- news: news
- download: download
- Subnav: subnav
- Menu: menu
- Submenu: submenu
- search: search
- Friendship link: friendlink
- Footer: footer
- copyright: copyright
- Scrolling: scroll
- Content: content
- Tab: tab
- Article list: List
- Prompt message: msg
- tips: tips
- Column title: title
- Join: joinus
- guide
- service: service
- Registration: register
- status: status
- Vote: vote
- partner: partner
2.4.2 class naming:
- Color: use the name of the color or hexadecimal code, such as
.red { color: red; } .f60 { color: #f60; } .ff8600 { color: #ff8600; }
- Font size, directly use "font + font size" as the name, such as
.font12px { font-size: 12px; } .font9pt {font-size: 9pt; }
- Alignment style, using the English name of the alignment target, such as
.left { float:left; } .bottom { float:bottom; }
- The title block style is named in the way of "category + function", such as
.barnews { } .barproduct { }
2.5 JS naming
- Use hump nomenclature;
- Constants and global variables are all capitalized;
- The hump naming method is used for the naming of variables, such as:
strParsor. maxLength;
- The camel nomenclature is used for the naming of the class, in which the first letter is capitalized, such as:
AccountInfo;EventHandler
- The command of the method must be a verb or a verb phrase, such as:
obj.getSomeValue()
- The name of the member variable of the private class is underlined (), For example:
var MyClass = function(){ var _buffer; this.doSomething = function(){ } } this._somePrivateVariable = statement;
- Variables prefixed with "is" or "has" should be Boolean;
- The term "init" as a variable name should be an initialization method;
- Names such as "i", "j", "k" (and so on) are recommended for iteration temporary variables;
- The Exception handling class recommends adding "Exception" or "Error" after the variable name;
3. JS coding specification
3.1 detailed rules
debugger statements are not allowed in production environments
- ✗ error
function isTruthy(x) { debugger return Boolean(x) }
- ‡ correct
function isTruthy(x) { return Boolean(x) }
Empty code blocks are not allowed
- ✗ error
if (foo) { } while (foo) { }
- ‡ correct
if (foo) { // empty } while (foo) { /* empty */ }
Semicolons are prohibited after statements
- ✗ error
var name = "ESLint"; object.method = function() { // ... };
- ‡ correct
var name = "ESLint" object.method = function() { // ... }
There should be a space before the parenthesis in the function definition
- ✗ error
function foo() { // ... } var bar = function() { // ... }; var bar = function foo() { // ... }; class Foo { constructor() { // ... } } var foo = { bar() { // ... } }; var foo = async() => 1
- ‡ correct
function foo () { // ... } var bar = function () { // ... }; var bar = function foo () { // ... }; class Foo { constructor () { // ... } } var foo = { bar () { // ... } }; var foo = async () => 1
White space characters cannot appear at the end of a statement (except for blank lines)
Trailing commas are prohibited
- ✗ error
var foo = { bar: "baz", qux: "quux", }
- ‡ correct
var foo = { bar: "baz", qux: "quux" }
No space is allowed before the colon of a key value pair, and there must be a space after the colon
- ✗ error
var obj = { "foo" : 42, "bar" :32 }
- ✓ correct
var obj = { "foo": 42, "bar": 32 }
Spaces must be reserved before and after keywords
- ✗ error
if(foo){ //... }else if(bar) { //... }else{ //... }
- ‡ correct
if (foo) { //... } else if (bar) { //... } else { //... }
Spaces must be left before and after operators
- ✗ error
a+b a+ b a +b a?b:c const a={b:1}; var {a=0}=bar; function foo(a=0) { }
- ‡ correct
a + b a + b a ? b : c const a = {b:1}; var {a = 0} = bar; function foo(a = 0) { }
Comments must be preceded by spaces
- ✗ error
//This is a comment with no whitespace at the beginning /*This is a comment with no whitespace at the beginning */
- ‡ correct
// This is a comment with a whitespace at the beginning /* This is a comment with a whitespace at the beginning */
Single quotation marks are used uniformly for strings except when escape is required
- ✗ error
console.log("hello there")
- ‡ correct
console.log('hello there') // If the string contains single quotation mark characters, double quotation marks can be used $("<div class='box'>")
Always use = = = instead==
Exception: obj == null can be used to check null | undefined
- ✗ error
if (name == 'John') if (name != 'John')
- ‡ correct
if (name === 'John') if (name !== 'John')
Use hump naming method (except Object key)
- ✗ error
// Package import import { no_camelcased } from "external-module" // Variable definition var my_favorite_color = "#112C85"; // Function definition function do_something() { // ... }
- ‡ correct
// Package import import { no_camelcased as camelCased } from "external-module" // Variable definition var myFavoriteColor = "#112C85"; // Function definition function doSomething() { // ... } // Object key allows non hump naming var obj = { my_pref: 1 }
[suggestion] indent with 4 spaces
- ✗ error
if (a) { var b = a function foo(c) { var d = c } }
- ‡ correct
if (a) { var b = a function foo(c) { var d = c } }
3.2 configuration
The above code specifications can be configured eslint Conduct static inspection and automatic repair
Gitlab CI
Use in CI warehouse eslint CI Configure to quickly access the gitlab CI conforming to this development specification. After each code submission, the static syntax check will be performed on the JS code of the specified directory.
4. Code submission specification
4.1 code self inspection
In order to ensure the quality of the code, the following checks must be completed before submitting the code
4.1.1 HTML
1. Text for page debugging is not allowed
2. Useless comment code segments are not allowed
4.1.2 JavaScript
1. Debugging statements, such as debugger and console, are not allowed Log, etc
2. Useless comment code segments are not allowed
4.2 submission remarks
Each code submission must have comments indicating what modifications have been made in this submission
commit classification
bugfix - online function bug
sprintfix - code modification not on-line (some bug s of function modules not on-line)
Minor - minor modifications (line breaks, spelling mistakes, etc.)
Feature - new feature description
5. Front end code comments
5.1 HTML comments
<!-- container --> <div class="container"> ... <!-- user name --> <div id="user_name"> ... </div> <!-- /user name --> ... </div> <!-- /container -->
5.2 CSS comments
If there is less content, you can only add comments at the top. If there is more content, you can add an end tag at the end / * comment content end*/
/* New task start */ .new-task{} /* New task name */ .task-name{color:\#333;} /* New task time */ .task-created-time{background:url(img/clock.png) no-repeat;} /* New task end */
5.3 JavaScript comments
The JavaScript comments are the same as above. If the function has parameters, it is recommended to briefly comment on the content and type of parameters.
For more specifications, please refer to http://open.oa.com/static_api/v3/index.html#doc/show?id=html_structure
6. References to documents or packages
1. Front end page: when referencing css and js in the page or configuring url path, you must use "absolute path" instead of.. // Relative way of reference, etc
2. Before publishing online, you need to check whether there are referenced static resources in the corresponding environment. Cross references between different environments are not allowed.