-
Notifications
You must be signed in to change notification settings - Fork 3
/
scripting-style.txt
218 lines (157 loc) · 5.14 KB
/
scripting-style.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
*scripting-style.txt* An unofficial style guide for Vim scripts
Vim scripting style guide *scripting-style*
1. Indentation and whitespace |scripting-style-whitespace|
2. Inline documentation |scripting-style-documentation|
3. Special keys |scripting-style-keys|
4. Commands |scripting-style-commands|
5. Naming conventions |scripting-style-naming|
==============================================================================
1. Indentation and whitespace *scripting-style-whitespace*
INDENTATION
Code must be indented with two spaces per indent level. Ex.: >
if has("eval")
let g:example = 1
endif
<
Line continuation should increase the indent by at least one level. The
backslash must be followed by at least one space. Ex.: >
let g:example = [
\ 'item1',
\ 'item2'
\ ]
<
Use one space plus normal indentation for statements that require it: >
autocmd FileType * if g:foo |
\ setlocal nospell |
\ else |
\ setlocal spell |
\ endif
<
BLANK LINES
Blank lines should be used to delineate groups of related statements.
Function definitions must be preceded and followed by one blank line.
Scripts should avoid consecutive blank lines.
TRAILING WHITESPACE
Lines must not end in a whitespace character. If you wish to, e.g., define a
map in which the {rhs} ends in a space, use the special <Space> notation
rather than a literal space character. Ex.: >
nnoremap <Leader>s :saveas<Space>
<
ASSIGNMENT
Variable assignment must include a single space on each side of the assignment
operator: >
" Right:
let g:foo = 'bar'
" Wrong:
let g:foo='bar'
<
Setting option values must NOT include whitespce before the assignment
operator: >
" Right:
set laststatus=2
" Wrong:
set laststatus =2
<
DOT OPERATOR
Use space at each side of a "." when used as string concatenation to
differentiate from access to a dictionary: >
" Right
echo dict.member1 . astring
" Wrong:
echo dict.member1.astring
<
==============================================================================
2. Inline documentation *scripting-style-documentation*
Comments should start with a space followed by a capitalized word. Ex.: >
" This is a comment
<
Vim settings should be enclosed in single quotes as is done in Vim's help
documentation. Ex.: >
" Make sure 'paste' is enabled
<
Likewise, Vim features should be prefixed with a plus sign: >
" Abort if +linebreak is missing
<
==============================================================================
3. Special keys *scripting-style-keys*
The names of special keys are case insensitive in Vim, however the following
conventions should be observed.
NON-ALPHANUMERIC KEYS
Non-alphanumeric keys should be written in mixed case. The general rule is
that they should be written as they appear in Vim's help documentation.
Examples include: >
<Space>
<CR>
<EOL>
<Nop>
<Leader>
<Plug>
<PageUp>
<
CHORDS
Chords should be written with the letter representing the modifier key
uppercase and any letter key lowercase. Non-alphanumeric keys included in the
chord should follow the convention above. Examples include: >
<C-a>
<A-b>
<C-Space>
<S-F4>
<
Note: This may be controversial, as Vim's documentation prefers <C-A> for
<C-a>. The latter was chosen for legibility and to avoid confusion with a
shifted letter key. This convention is also used in the book Practical Vim,
for instance.
==============================================================================
4. Commands *scripting-style-commands*
GENERAL
The optional leading : must be omitted in scripts. Ex.: >
" Right:
function dict.init() dict
let self.val = 0
endfunction
" Wrong:
:function dict.init() dict
: let self.val = 0
:endfunction
<
ABBREVIATIONS
Commands must never be abbreviated in scripts. Using the unabbreviated forms
of built-in and user-defined commands promotes consistency and thus improves
legibility. Ex.: >
" Right:
setlocal linebreak
" Wrong:
setl lbr
<
SETTING OPTIONS
Toggling or inverting options should be done with :set {option}! rather than
:set inv{option}, since the former is more common and easier to read. Ex.: >
" Right:
set number!
" Wrong:
set invnumber
<
Setting {option} to {value} should be done with the more common '=' rather than
':'. Ex.: >
" Right:
set filetype=vim
" Wrong:
set filetype:vim
<
==============================================================================
5. Naming conventions *scripting-style-naming*
SCRIPTS
All filenames and directories must use snake case. Ex.: >
my_plugin.vim
autoload/my_plugin/my_functions.vim
<
VARIABLES
All normal variables must be written in snake case. Ex.: >
let g:my_var = 1
<
Note: This does not apply to, e.g., |Funcref| variables, which must start with
a capital letter.
A variable's scope must always be stated explicitly. That means that
function-local and global variables must be prefixed with l: and g:
respectively even in contexts where the prefixes are optional.
vim:tw=78:ts=8:ft=help:norl: