Skip to content

Commit deb4c66

Browse files
unknwonunknwon
committed
naming rules
1 parent 80bb8d2 commit deb4c66

File tree

3 files changed

+220
-28
lines changed

3 files changed

+220
-28
lines changed

‎en-US/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,5 @@ This manual is based on [Unknwon](https://github.com/Unknwon)'s develop experien
88
- [Project Structure](project_structure.md)
99
- [Import Packages](import_packages.md)
1010
- [Commentary](commentary.md)
11+
- [Naming Rules](naming_rules.md)
1112
- [Test Cases](test_case.md)

‎en-US/naming_rules.md

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Naming Rules
2+
3+
### File name
4+
5+
- The main entry point file of the application should be named as `main.go` or same as the application. For example, the entry point file of `Gogs` is named `gogs.go`.
6+
7+
### Functions and Methods
8+
9+
- If the main purpose of functions or methods is returning a `bool` type value, the name of function or method should starts with `Has`, `Is`, `Can` or `Allow`, etc.
10+
11+
```go
12+
func HasPrefix(name string, prefixes []string) bool { ... }
13+
func IsEntry(name string, entries []string) bool { ... }
14+
func CanManage(name string) bool { ... }
15+
func AllowGitHook() bool { ... }
16+
```
17+
18+
### Constants
19+
20+
- Constant should use all capital letters and use underscore `_` to separate words.
21+
22+
```go
23+
const APP_VER = "0.7.0.1110 Beta"
24+
```
25+
26+
- If you need enumerated type, you should define the corresponding type first:
27+
28+
```go
29+
type Scheme string
30+
31+
const (
32+
HTTP Scheme = "http"
33+
HTTPS Scheme = "https"
34+
)
35+
```
36+
37+
- If functionality of the module is relatively complicated and easy to mixed up with constant name, you can add prefix to every constant:
38+
39+
```go
40+
type PullRequestStatus int
41+
42+
const (
43+
PULL_REQUEST_STATUS_CONFLICT PullRequestStatus = iota
44+
PULL_REQUEST_STATUS_CHECKING
45+
PULL_REQUEST_STATUS_MERGEABLE
46+
)
47+
```
48+
49+
### Variables
50+
51+
- A variable name should follow general English expression or shorthand.
52+
- In relatively simple (less objects and more specific) context, variable name can use simplified form as follows:
53+
- `user` to `u`
54+
- `userID` to `uid`
55+
- If variable type is `bool`, its name should start with `Has`, `Is`, `Can` or `Allow`, etc.
56+
57+
```go
58+
var isExist bool
59+
var hasConflict bool
60+
var canManage bool
61+
var allowGitHook bool
62+
```
63+
64+
- The last rule also applies for defining structs:
65+
66+
```go
67+
// Webhook represents a web hook object.
68+
type Webhook struct {
69+
ID int64 `xorm:"pk autoincr"`
70+
RepoID int64
71+
OrgID int64
72+
URL string `xorm:"url TEXT"`
73+
ContentType HookContentType
74+
Secret string `xorm:"TEXT"`
75+
Events string `xorm:"TEXT"`
76+
*HookEvent `xorm:"-"`
77+
IsSSL bool `xorm:"is_ssl"`
78+
IsActive bool
79+
HookTaskType HookTaskType
80+
Meta string `xorm:"TEXT"` // store hook-specific attributes
81+
LastStatus HookStatus // Last delivery status
82+
Created time.Time `xorm:"CREATED"`
83+
Updated time.Time `xorm:"UPDATED"`
84+
}
85+
```
86+
87+
#### Variable Naming Convention
88+
89+
Variable name is generally using Camel Case style, but when you have unique nouns, should apply following rules:
90+
91+
- If the variable is private, and the unique noun is the first word, then use lower cases, e.g. `apiClient`.
92+
- Otherwise, use the original cases for the unique noun, e.g. `APIClient`, `repoID`, `UserID`.
93+
94+
Here is a list of words which are commonly identified as unique nouns:
95+
96+
```go
97+
// A GonicMapper that contains a list of common initialisms taken from golang/lint
98+
var LintGonicMapper = GonicMapper{
99+
"API": true,
100+
"ASCII": true,
101+
"CPU": true,
102+
"CSS": true,
103+
"DNS": true,
104+
"EOF": true,
105+
"GUID": true,
106+
"HTML": true,
107+
"HTTP": true,
108+
"HTTPS": true,
109+
"ID": true,
110+
"IP": true,
111+
"JSON": true,
112+
"LHS": true,
113+
"QPS": true,
114+
"RAM": true,
115+
"RHS": true,
116+
"RPC": true,
117+
"SLA": true,
118+
"SMTP": true,
119+
"SSH": true,
120+
"TLS": true,
121+
"TTL": true,
122+
"UI": true,
123+
"UID": true,
124+
"UUID": true,
125+
"URI": true,
126+
"URL": true,
127+
"UTF8": true,
128+
"VM": true,
129+
"XML": true,
130+
"XSRF": true,
131+
"XSS": true,
132+
}
133+
```

‎zh-CN/naming_rules.md

Lines changed: 86 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -2,44 +2,56 @@
22

33
### 文件名
44

5-
- 包含应用 `main` 函数的文件为整个项目的主文件，需要与应用名称简写相同。例如：`Gogs` 的主文件需命名为 `gogs.go`。
5+
- 整个应用或包的主入口文件应当是 `main.go` 或与应用名称简写相同。例如：`Gogs` 的主入口文件名为 `gogs.go`。
66

77
### 函数或方法
88

99
- 若函数或方法为判断类型（返回值主要为 `bool` 类型），则名称应以 `Has`, `Is`, `Can` 或 `Allow` 等判断性动词开头：
1010

1111
```go
12-
func HasPrefix(name string, prefixes []string) bool { ...
13-
func IsEntry(name string, entries []string) bool { ...
14-
func CanManage(name string) bool { ...
15-
func AllowGitHook() bool { ...
12+
func HasPrefix(name string, prefixes []string) bool { ... }
13+
func IsEntry(name string, entries []string) bool { ... }
14+
func CanManage(name string) bool { ... }
15+
func AllowGitHook() bool { ... }
1616
```
17-
17+
1818
### 常量
1919

2020
- 常量均需使用全部大写字母组成，并使用下划线分词：
2121

2222
```go
23-
const APP_VER = "0.3.5.0519 Alpha"
23+
const APP_VER = "0.7.0.1110 Beta"
2424
```
25-
25+
2626
- 如果是枚举类型的常量，需要先创建相应类型：
2727

2828
```go
2929
type Scheme string
30-
30+
3131
const (
3232
HTTP Scheme = "http"
3333
HTTPS Scheme = "https"
3434
)
3535
```
3636

37+
- 如果模块的功能较为复杂、常量名称容易混淆的情况下，为了更好地区分枚举类型，可以使用完整的前缀：
38+
39+
```go
40+
type PullRequestStatus int
41+
42+
const (
43+
PULL_REQUEST_STATUS_CONFLICT PullRequestStatus = iota
44+
PULL_REQUEST_STATUS_CHECKING
45+
PULL_REQUEST_STATUS_MERGEABLE
46+
)
47+
```
48+
3749
### 变量
3850

39-
- 变量命名基本上遵循相应的英文翻译。
51+
- 变量命名基本上遵循相应的英文表达或简写。
4052
- 在相对简单的环境（对象数量少、针对性强）中，可以将一些名称由完整单词简写为单个字母，例如：
4153
- `user` 可以简写为 `u`
42-
- `userId` 可以简写 `uid`
54+
- `userID` 可以简写 `uid`
4355
- 若变量类型为 `bool` 类型，则名称应以 `Has`, `Is`, `Can` 或 `Allow` 开头：
4456

4557
```go
@@ -48,28 +60,74 @@
4860
var canManage bool
4961
var allowGitHook bool
5062
```
51-
- 上条规则也适用于 ORM 模型：
63+
64+
- 上条规则也适用于结构定义：
5265

5366
```go
67+
// Webhook represents a web hook object.
5468
type Webhook struct {
55-
Id int64
56-
RepoId int64
57-
Url string `xorm:"TEXT"`
58-
ContentType int
59-
Secret string `xorm:"TEXT"`
60-
Events string `xorm:"TEXT"`
61-
*HookEvent `xorm:"-"`
62-
IsSsl bool
63-
IsActive bool
64-
HasAvatar bool
65-
CanManage bool
66-
AllowGitHook bool
69+
ID int64 `xorm:"pk autoincr"`
70+
RepoID int64
71+
OrgID int64
72+
URL string `xorm:"url TEXT"`
73+
ContentType HookContentType
74+
Secret string `xorm:"TEXT"`
75+
Events string `xorm:"TEXT"`
76+
*HookEvent `xorm:"-"`
77+
IsSSL bool `xorm:"is_ssl"`
78+
IsActive bool
79+
HookTaskType HookTaskType
80+
Meta string `xorm:"TEXT"` // store hook-specific attributes
81+
LastStatus HookStatus // Last delivery status
82+
Created time.Time `xorm:"CREATED"`
83+
Updated time.Time `xorm:"UPDATED"`
6784
}
6885
```
6986

7087
#### 变量命名惯例
7188

72-
- 代表某个用户：`u`
73-
- 代表某个用户 ID：`uid`
74-
- 代表某个索引：`idx`
75-
- 代表某个值：`val`
89+
变量名称一般遵循驼峰法，但遇到特有名词时，需要遵循以下规则：
90+
91+
- 如果变量为私有，且特有名词为首个单词，则使用小写，如 `apiClient`。
92+
- 其它情况都应当使用该名词原有的写法，如 `APIClient`、`repoID`、`UserID`。
93+
94+
下面列举了一些常见的特有名词：
95+
96+
```go
97+
// A GonicMapper that contains a list of common initialisms taken from golang/lint
98+
var LintGonicMapper = GonicMapper{
99+
"API": true,
100+
"ASCII": true,
101+
"CPU": true,
102+
"CSS": true,
103+
"DNS": true,
104+
"EOF": true,
105+
"GUID": true,
106+
"HTML": true,
107+
"HTTP": true,
108+
"HTTPS": true,
109+
"ID": true,
110+
"IP": true,
111+
"JSON": true,
112+
"LHS": true,
113+
"QPS": true,
114+
"RAM": true,
115+
"RHS": true,
116+
"RPC": true,
117+
"SLA": true,
118+
"SMTP": true,
119+
"SSH": true,
120+
"TLS": true,
121+
"TTL": true,
122+
"UI": true,
123+
"UID": true,
124+
"UUID": true,
125+
"URI": true,
126+
"URL": true,
127+
"UTF8": true,
128+
"VM": true,
129+
"XML": true,
130+
"XSRF": true,
131+
"XSS": true,
132+
}
133+
```

0 commit comments

Comments
 (0)