mirror of
https://github.com/cocos/cocos4.git
synced 2026-11-19 14:52:40 +08:00
5746790a78
* Improve engine repo readme * Add ts coding style reference and improve contribution guide * Temporary remove screen shots section * minor change
613 lines
12 KiB
Markdown
613 lines
12 KiB
Markdown
# TypeScript and JavaScript Coding Style Reference
|
|
|
|
The following are some coding style rules for TypeScript and JavaScript we concluded during the development of Cocos Creator. It's important to mention that it's based on some basic conventions and our practices. Due to the fact that TypeScript compiler and JavaScript engine is keep evolving rapidly, we try to make the references quite simple.
|
|
|
|
There are also some project related background need to be clarified:
|
|
|
|
1. TypeScript is used for script level code in the engine.
|
|
2. [Babel](https://babeljs.io/) and [Rollup](https://rollupjs.org/) are used to compile TypeScript to JavaScript.
|
|
3. [ESLint](https://eslint.org/) is strongly recommended for all engine developers.
|
|
4. [VSCode](https://code.visualstudio.com/) is suggested for TypeScript coding.
|
|
5. In web runtime environments, the engine is fully running compiled TypeScript codes with some WebAssembly modules like physics engine.
|
|
6. In native runtime environments, the TypeScript codes are running based on the C++ codes and the JavaScript binding.
|
|
|
|
## Naming Rules
|
|
|
|
- Use camelCase naming convention for object and instance variables, properties, functions and namespaces.
|
|
|
|
```typescript
|
|
// bad
|
|
let FOOBar = {};
|
|
let foo_bar = {};
|
|
function FOOBar () {}
|
|
|
|
// good
|
|
let fooBar = {};
|
|
function fooBar () {}
|
|
```
|
|
|
|
- When using acronym for variables, properties or functions, keep all characters of the acronym case aligned. If the name starts with acronym then use lower case for all characters, otherwise capitalize all characters.
|
|
|
|
```typescript
|
|
// bad
|
|
let Id = 0;
|
|
let iD = 0;
|
|
function requireId () {}
|
|
|
|
// good
|
|
let id = 0;
|
|
let uuid = '';
|
|
function requireID () {}
|
|
class AssetUUID {}
|
|
```
|
|
|
|
- Use PascalCase naming convention for classes or modules
|
|
|
|
```javascript
|
|
// bad
|
|
let foobar = cc.Class({
|
|
foo: 'foo',
|
|
bar: 'bar',
|
|
});
|
|
let foobar = require('foo-bar');
|
|
|
|
// good
|
|
let FooBar = cc.Class({
|
|
foo: 'foo',
|
|
bar: 'bar',
|
|
});
|
|
let FooBar = require('foo-bar');
|
|
```
|
|
|
|
- Accessor API conventions
|
|
- Declare `public` property when the property is a direct value.
|
|
|
|
```typescript
|
|
// bad
|
|
class A {
|
|
get a ():number {
|
|
return this._a;
|
|
}
|
|
set a (val:number) {
|
|
this._a = val;
|
|
}
|
|
private _a: number;
|
|
}
|
|
// good
|
|
class A {
|
|
public a: number;
|
|
}
|
|
```
|
|
|
|
- Suggest to make the property private and provide `getXXX/setXXX` methods when data accessing requires heavy logic.
|
|
- Suggest to make the property private and provide `getXXX/setXXX` methods when data accessing implicitly affect other data.
|
|
|
|
```typescript
|
|
// not recommended
|
|
class A {
|
|
get property ():number {
|
|
// computeResult have some heavy logic
|
|
return this.computeResult();
|
|
}
|
|
}
|
|
// recommended
|
|
class A {
|
|
getProperty ():number {
|
|
// computeResult have some heavy logic
|
|
return this.computeResult();
|
|
}
|
|
}
|
|
|
|
// ---
|
|
|
|
// not recommended
|
|
class A {
|
|
get property ():number {
|
|
return this._prop;
|
|
}
|
|
set property (val: number) {
|
|
this._prop = val;
|
|
this._a = this.computeA();
|
|
}
|
|
|
|
private _prop: number;
|
|
private _a: number;
|
|
}
|
|
// recommended
|
|
class A {
|
|
getProperty ():number {
|
|
return this._prop;
|
|
}
|
|
setProperty (val: number) {
|
|
this._prop = val;
|
|
this._a = this.computeA();
|
|
}
|
|
|
|
private _prop: number;
|
|
private _a: number;
|
|
}
|
|
```
|
|
|
|
- Suggest to make the property private and provide public accessors if data accessing is light weight.
|
|
- In other conditions, please follow the existing API design in the file context.
|
|
|
|
- Use all capitalized characters with underscores as word separator for CONSTANTS.
|
|
|
|
```typescript
|
|
// bad
|
|
const PRIVATE_letIABLE = 'should not be unnecessarily uppercased within a file';
|
|
|
|
// bad
|
|
let THING_TO_BE_CHANGED = 'should obviously not be uppercased';
|
|
|
|
// bad
|
|
let REASSIGNABLE_letIABLE = 'do not use let with uppercase letiables';
|
|
|
|
// ---
|
|
|
|
// allowed but does not supply semantic value
|
|
export const apiKey = 'SOMEKEY';
|
|
|
|
// better in most cases
|
|
export const API_KEY = 'SOMEKEY';
|
|
|
|
// ---
|
|
|
|
// bad - unnecessarily uppercases key while adding no semantic value
|
|
export const MAPPING = {
|
|
KEY: 'value'
|
|
};
|
|
|
|
// good
|
|
export const Type = {
|
|
SIMPLE: 'value'
|
|
};
|
|
```
|
|
|
|
- Use underscore `_` as prefix for private properties.
|
|
|
|
```typescript
|
|
// bad
|
|
class A {
|
|
private __firstName__: string;
|
|
private firstName_: string;
|
|
}
|
|
|
|
// good
|
|
class A {
|
|
private _firstName: string;
|
|
}
|
|
```
|
|
|
|
- Use lowercase characters with dash `-` as word separator for TypeScript file names.
|
|
|
|
```bash
|
|
// bad
|
|
fooBar.ts
|
|
FooBar.ts
|
|
|
|
// good
|
|
foo-bar.ts
|
|
```
|
|
|
|
## Syntax references
|
|
|
|
- If a class property doesn't contain any initialization value, should consider using declare to avoid potential [issue](https://github.com/microsoft/TypeScript/issues/37640)
|
|
|
|
```typescript
|
|
// bad
|
|
class A {
|
|
public a:number;
|
|
constructor (a:number) {
|
|
// After compilation, the following line would be added to the constructor.
|
|
// this.a = void 0;
|
|
// As the type of `a` is changing, this could cause performance issue
|
|
this.a = a;
|
|
}
|
|
}
|
|
|
|
// good
|
|
class A {
|
|
public a:number = 0; // Ok.
|
|
constructor (a:number) {
|
|
// After compilation, the following line would be added to the constructor.
|
|
// this.a = 0;
|
|
// The type of `a` is constant
|
|
this.a = a;
|
|
}
|
|
}
|
|
|
|
// best
|
|
class A {
|
|
public declare a:number;
|
|
public b:undefined | object; // OK: b won't be reassigned in constructor
|
|
public declare c:object|null;
|
|
|
|
constructor (a:number, c:object) {
|
|
this.a = a;
|
|
this.c = c;
|
|
}
|
|
}
|
|
```
|
|
|
|
- Suggest to use `Object.create(null)` to create dictionaries, whose contents will be added or deleted frequently.
|
|
|
|
```javascript
|
|
// bad
|
|
let map = new Object();
|
|
|
|
// bad
|
|
let map = {};
|
|
|
|
// good
|
|
let map = Object.create(null);
|
|
```
|
|
|
|
- Use strict comparison `===` and `!==` instead of `==` and `!=`
|
|
|
|
## Other coding conventions
|
|
|
|
- Use 4 spaces indent.
|
|
|
|
```typescript
|
|
// bad
|
|
function () {
|
|
∙let name;
|
|
}
|
|
|
|
// bad
|
|
function () {
|
|
∙∙let name;
|
|
}
|
|
|
|
// very bad
|
|
function () {
|
|
∙∙<tab>let name;
|
|
}
|
|
|
|
// good
|
|
function () {
|
|
∙∙∙∙let name;
|
|
}
|
|
```
|
|
|
|
- Don't leave tailed spaces, and leave an empty line at the end of the file.
|
|
|
|
```typescript
|
|
// bad
|
|
function () {∙
|
|
∙∙∙∙let name;∙
|
|
}
|
|
/* EOF */
|
|
|
|
// good
|
|
function () {
|
|
∙∙∙∙let name;
|
|
}
|
|
|
|
/* EOF */
|
|
```
|
|
|
|
- Always add `;` at the end of a code line.
|
|
|
|
```typescript
|
|
// bad
|
|
proto.foo = function () {
|
|
}
|
|
|
|
// good
|
|
proto.foo = function () {
|
|
};
|
|
|
|
// bad
|
|
function foo () {
|
|
return 'test'
|
|
}
|
|
|
|
// very bad
|
|
// returns `undefined` instead of the value on the next line,
|
|
// always happens when `return` is on a line by itself because of Automatic Semicolon Insertion!
|
|
function foo () {
|
|
return
|
|
'test'
|
|
}
|
|
|
|
// good
|
|
function foo () {
|
|
return 'test';
|
|
}
|
|
|
|
// bad
|
|
function foo () {
|
|
};
|
|
|
|
// good: this is not a code line
|
|
function foo () {
|
|
}
|
|
```
|
|
|
|
- Suggest to keep `{` with the previous line.
|
|
|
|
```typescript
|
|
// bad
|
|
if ( isFoobar )
|
|
{
|
|
}
|
|
|
|
// good
|
|
if ( isFoobar ) {
|
|
}
|
|
|
|
// bad
|
|
function foobar ()
|
|
{
|
|
}
|
|
|
|
// good
|
|
function foobar () {
|
|
}
|
|
|
|
// bad
|
|
let obj =
|
|
{
|
|
foo: 'foo',
|
|
bar: 'bar',
|
|
}
|
|
|
|
// good
|
|
let obj = {
|
|
foo: 'foo',
|
|
bar: 'bar',
|
|
}
|
|
```
|
|
|
|
- Leave one space before `{`
|
|
|
|
```typescript
|
|
// bad
|
|
if (isJedi){
|
|
fight();
|
|
}
|
|
else{
|
|
escape();
|
|
}
|
|
|
|
// good
|
|
if (isJedi) {
|
|
fight();
|
|
}
|
|
else {
|
|
escape();
|
|
}
|
|
|
|
// bad
|
|
dog.set('attr',{
|
|
age: '1 year',
|
|
breed: 'Bernese Mountain Dog',
|
|
});
|
|
|
|
// good
|
|
dog.set('attr', {
|
|
age: '1 year',
|
|
breed: 'Bernese Mountain Dog',
|
|
});
|
|
```
|
|
|
|
- Leave one space after `if`, `else`, `while` and `switch`
|
|
|
|
```typescript
|
|
// bad
|
|
if(isJedi) {
|
|
fight ();
|
|
}
|
|
else{
|
|
escape();
|
|
}
|
|
|
|
// good
|
|
if (isJedi) {
|
|
fight();
|
|
}
|
|
else {
|
|
escape();
|
|
}
|
|
```
|
|
|
|
- Leave one space before and after binary and ternary operators.
|
|
|
|
```typescript
|
|
// bad
|
|
let x=y+5;
|
|
let left = rotated? y: x;
|
|
|
|
// good
|
|
let x = y + 5;
|
|
let left = rotated ? y : x;
|
|
|
|
// bad
|
|
for (let i=0; i< 10; i++) {
|
|
}
|
|
|
|
// good
|
|
for (let i = 0; i < 10; i++) {
|
|
}
|
|
```
|
|
|
|
- Some function declaration references
|
|
|
|
```typescript
|
|
// bad
|
|
let test = function () {
|
|
console.log('test');
|
|
};
|
|
|
|
// good
|
|
function test () {
|
|
console.log('test');
|
|
}
|
|
|
|
// bad
|
|
function test () { console.log('test'); };
|
|
|
|
// good
|
|
function test () {
|
|
console.log('test');
|
|
}
|
|
|
|
// bad
|
|
function divisibleFunction () {
|
|
return DEBUG ? 'foo' : 'bar';
|
|
}
|
|
|
|
// best
|
|
let divisibleFunction = DEBUG ?
|
|
function () {
|
|
return 'foo';
|
|
} :
|
|
function () {
|
|
return 'bar';
|
|
};
|
|
|
|
// bad
|
|
function test(){
|
|
}
|
|
|
|
// good
|
|
function test () {
|
|
}
|
|
|
|
// bad
|
|
let obj = {
|
|
foo: function () {
|
|
}
|
|
};
|
|
|
|
// good
|
|
let obj = {
|
|
foo () {
|
|
}
|
|
};
|
|
|
|
// bad
|
|
array.map(x=>x + 1);
|
|
array.map(x => {
|
|
return x + 1;
|
|
});
|
|
|
|
// good
|
|
array.map(x => x + 1);
|
|
```
|
|
|
|
- Suggest to leave empty line between code blocks.
|
|
|
|
```typescript
|
|
// bad
|
|
if (foo) {
|
|
return bar;
|
|
}
|
|
return baz;
|
|
|
|
// good
|
|
if (foo) {
|
|
return bar;
|
|
}
|
|
|
|
return baz;
|
|
|
|
// bad
|
|
const obj = {
|
|
x: 0,
|
|
y: 0,
|
|
foo () {
|
|
},
|
|
bar () {
|
|
},
|
|
};
|
|
return obj;
|
|
|
|
// good
|
|
const obj = {
|
|
x: 0,
|
|
y: 0,
|
|
|
|
foo () {
|
|
},
|
|
|
|
bar () {
|
|
},
|
|
};
|
|
|
|
return obj;
|
|
```
|
|
|
|
- Semicolon alignment.
|
|
|
|
```typescript
|
|
// bad
|
|
let story = [
|
|
once
|
|
, upon
|
|
, aTime
|
|
];
|
|
|
|
// good
|
|
let story = [
|
|
once,
|
|
upon,
|
|
aTime,
|
|
];
|
|
|
|
// bad
|
|
let hero = {
|
|
firstName: 'Ada'
|
|
, lastName: 'Lovelace'
|
|
, birthYear: 1815
|
|
, superPower: 'computers'
|
|
};
|
|
|
|
// good
|
|
let hero = {
|
|
firstName: 'Ada',
|
|
lastName: 'Lovelace',
|
|
birthYear: 1815,
|
|
superPower: 'computers',
|
|
};
|
|
```
|
|
|
|
- Single line comments
|
|
|
|
```typescript
|
|
//bad
|
|
// good
|
|
```
|
|
|
|
- Multiple line comments
|
|
|
|
```typescript
|
|
/*
|
|
* good
|
|
*/
|
|
```
|
|
|
|
- API documentation comments
|
|
|
|
```typescript
|
|
/**
|
|
* good
|
|
*/
|
|
```
|
|
|
|
- Except for API documentation, all comments must be written in English
|
|
|
|
```js
|
|
// bad
|
|
// 中文注释不利于非中文开发者阅读代码
|
|
// good
|
|
// Please write all in file comments in English
|
|
```
|
|
|
|
## Other references
|
|
|
|
- [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)
|
|
- [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript#table-of-contents)
|