Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / google-styleguide / refs/tags/rel/11/fp3/8901.4.A.0021.0 / . / vimscriptguide.xml
blob: 2baf3fd61a512bdfead55b867d57d03eb2115dba [file] [log] [blame]
dbarnett@google.com4882d602014-04-12 06:08:42 +0000[diff] [blame]1<?xml version = '1.0'?>
2<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
3<GUIDE title="Google Vimscript Style Guide">
4 <p class="revision">
5
6 Revision 1.1
7 </p>
8
9
10 <address>
11 Nate Soares<br/>
12 Joshua Hoak<br/>
13 David Barnett<br/>
14 </address>
15
16 <OVERVIEW>
17 <CATEGORY title="Background">
18 <p>
19 This is a casual version of the vimscript style guide, because
20 vimscript is a casual language. When submitting vim plugin code, you
21 must adhere to these rules. For clarifications, justifications, and
22 explanations about the finer points of vimscript, please refer to the
23 <a href="vimscriptfull.xml">heavy guide</a>.
24 </p>
25 </CATEGORY>
26 </OVERVIEW>
27
28 <CATEGORY title="Portability">
29 <p>
30 It's hard to get vimscript right. Many commands depend upon the user's
31 settings. By following these guidelines, you can hope to make your
32 scripts portable.
33 </p>
34 <STYLEPOINT title="Strings">
35 <SUMMARY>Prefer single quoted strings</SUMMARY>
36 <BODY>
37 <p>
38 Double quoted strings are semantically different in vimscript, and
39 you probably don't want them (they break regexes).
40 </p>
41 <p>
42 Use double quoted strings when you need an escape sequence (such as
43 <code>"\n"</code>) or if you know it doesn't matter and you need to
44 embed single quotes.
45 </p>
46 </BODY>
47 </STYLEPOINT>
48 <STYLEPOINT title="Matching Strings">
49 <SUMMARY>
50 Use the <code>=~#</code> or <code>=~?</code> operator families over the
51 <code>=~</code> family.
52 </SUMMARY>
53 <BODY>
54 <p>
55 The matching behavior depends upon the user's ignorecase and smartcase
56 settings and on whether you compare them with the <code>=~</code>,
57 <code>=~#</code>, or <code>=~?</code> family of operators. Use the
58 <code>=~#</code> and <code>=~?</code> operator families explicitly
59 when comparing strings unless you explicitly need to honor the user's
60 case sensitivity settings.
61 </p>
62 </BODY>
63 </STYLEPOINT>
64 <STYLEPOINT title="Regular Expressions">
65 <SUMMARY>Prefix all regexes with <code>\m\C</code>.</SUMMARY>
66 <BODY>
67 <p>
68 In addition to the case sensitivity settings, regex behavior depends
69 upon the user's nomagic setting. To make regexes act like nomagic and
70 noignorecase are set, prepend all regexes with <code>\m\C</code>.
71 </p>
72 <p>
73 You are welcome to use other magic levels (<code>\v</code>) and case
74 sensitivities (<code>\c</code>) so long as they are intentional and
75 explicit.
76 </p>
77 </BODY>
78 </STYLEPOINT>
79 <STYLEPOINT title="Dangerous commands">
80 <SUMMARY>Avoid commands with unintended side effects.</SUMMARY>
81 <BODY>
82 <p>
83 Avoid using <code>:s[ubstitute]</code> as it moves the cursor and
84 prints error messages. Prefer functions (such as
85 <code>search()</code>) better suited to scripts.
86 </p>
87 <p>
88 For many vim commands, functions exist that do the same thing with
89 fewer side effects. See <code>:help functions()</code> for a list of
90 built-in functions.
91 </p>
92 </BODY>
93 </STYLEPOINT>
94 <STYLEPOINT title="Fragile commands">
95 <SUMMARY>Avoid commands that rely on user settings.</SUMMARY>
96 <BODY>
97 <p>
98 Always use <code>normal!</code> instead of <code>normal</code>. The
99 latter depends upon the user's key mappings and could do anything.
100 </p>
101 <p>
102 Avoid <code>:s[ubstitute]</code>, as its behavior depends upon a
103 number of local settings.
104 </p>
105 <p>
106 The same applies to other commands not listed here.
107 </p>
108 </BODY>
109 </STYLEPOINT>
110 <STYLEPOINT title="Catching Exceptions">
111 <SUMMARY>Match error codes, not error text.</SUMMARY>
112 <BODY>
113 <p>Error text may be locale dependant.</p>
114 </BODY>
115 </STYLEPOINT>
116 </CATEGORY>
117
118 <CATEGORY title="General Guidelines">
119
120
121 <STYLEPOINT title="Messaging">
122 <SUMMARY>Message the user infrequently.</SUMMARY>
123 <BODY>
124 <p>
125 Loud scripts are annoying. Message the user only when:
126 <ul>
127 <li>A long-running process has kicked off.</li>
128 <li>An error has occurred.</li>
129 </ul>
130 </p>
131 </BODY>
132 </STYLEPOINT>
133 <STYLEPOINT title="Type checking">
134 <SUMMARY>Use strict and explicit checks where possible.</SUMMARY>
135 <BODY>
136 <p>
137 Vimscript has unsafe, unintuitive behavior when dealing with some
138 types. For instance, <code>0 == 'foo'</code> evaluates to true.
139 </p>
140 <p>
141 Use strict comparison operators where possible. When comparing against
142 a string literal, use the <code>is#</code> operator. Otherwise, prefer
143 <code>maktaba#value#IsEqual</code> or check <code>type()</code>
144 explicitly.
145 </p>
146 <p>
147 Check variable types explicitly before using them. Use functions from
148 <code>maktaba#ensure</code>, or check <code>maktaba#value</code> or
149 <code>type()</code> and throw your own errors.
150 </p>
151 <p>
152 Use <code>:unlet</code> for variables that may change types,
153 particularly those assigned inside loops.
154 </p>
155 </BODY>
156 </STYLEPOINT>
157 <STYLEPOINT title="Python">
158 <SUMMARY>Use sparingly.</SUMMARY>
159 <BODY>
160 <p>
161 Use python only when it provides critical functionality, for example
162 when writing threaded code.
163 </p>
164 </BODY>
165 </STYLEPOINT>
166 <STYLEPOINT title="Other Languages">
167 <SUMMARY>Use vimscript instead.</SUMMARY>
168 <BODY>
169 <p>
170 Avoid using other scripting languages such as ruby and lua. We can
171 not guarantee that the end user's vim has been compiled with support
172 for non-vimscript languages.
173 </p>
174 </BODY>
175 </STYLEPOINT>
176 <STYLEPOINT title="Boilerplate">
177 <SUMMARY>
178 Use <a href="https://github.com/google/maktaba">maktaba</a>.
179 </SUMMARY>
180 <BODY>
181 <p>
182 maktaba removes boilerplate, including:
183 <ul>
184 <li>Plugin creation</li>
185 <li>Error handling</li>
186 <li>Dependency checking</li>
187 </ul>
188 </p>
189 </BODY>
190 </STYLEPOINT>
191 <STYLEPOINT title="Plugin layout">
192 <SUMMARY>Organize functionality into modular plugins</SUMMARY>
193 <BODY>
194 <p>
195 Group your functionality as a plugin, unified in one directory (or
196 code repository) which shares your plugin's name (with a "vim-" prefix
197 or ".vim" suffix if desired). It should be split into plugin/,
198 autoload/, etc. subdirectories as necessary, and it should declare
199 metadata in the addon-info.json format (see the
Ackermann Yuriyacb4f902016-04-01 21:36:44 +1300[diff] [blame]200 <a href="https://github.com/MarcWeber/vim-addon-manager/blob/master/doc/vim-addon-manager-additional-documentation.txt">VAM documentation</a> for details).
dbarnett@google.com4882d602014-04-12 06:08:42 +0000[diff] [blame]201 </p>
202 </BODY>
203 </STYLEPOINT>
204 <STYLEPOINT title="Functions">
205 <SUMMARY>
206 In the autoload/ directory, defined with <code>[!]</code> and
207 <code>[abort]</code>.
208 </SUMMARY>
209 <BODY>
210 <p>
211 Autoloading allows functions to be loaded on demand, which makes
212 startuptime faster and enforces function namespacing.
213 </p>
214 <p>
215 Script-local functions are welcome, but should also live in autoload/
216 and be called by autoloaded functions.
217 </p>
218 <p>
219 Non-library plugins should expose commands instead of functions.
220 Command logic should be extracted into functions and autoloaded.
221 </p>
222 <p>
223 <code>[!]</code> allows developers to reload their functions
224 without complaint.
225 </p>
226 <p>
227 <code>[abort]</code> forces the function to halt when it encounters
228 an error.
229 </p>
230 </BODY>
231 </STYLEPOINT>
232 <STYLEPOINT title="Commands">
233 <SUMMARY>
234 In the plugin/commands.vim or under the ftplugin/ directory, defined
235 without <code>[!]</code>.
236 </SUMMARY>
237 <BODY>
238 <p>
239 General commands go in <code>plugin/commands.vim</code>.
240 Filetype-specific commands go in <code>ftplugin/</code>.
241 </p>
242 <p>
243 Excluding <code>[!]</code> prevents your plugin from silently
244 clobbering existing commands. Command conflicts should be resolved by
245 the user.
246 </p>
247 </BODY>
248 </STYLEPOINT>
249 <STYLEPOINT title="Autocommands">
250 <SUMMARY>
251 Place them in plugin/autocmds.vim, within augroups.
252 </SUMMARY>
253 <BODY>
254 <p>
255 Place all autocommands in augroups.
256 </p>
257 <p>
258 The augroup name should be unique. It should either be, or be prefixed
259 with, the plugin name.
260 </p>
261 <p>
262 Clear the augroup with <code>autocmd!</code> before defining new
263 autocommands in the augroup. This makes your plugin re-entrable.
264 </p>
265 </BODY>
266 </STYLEPOINT>
267 <STYLEPOINT title="Mappings">
268 <SUMMARY>
269 Place them in <code>plugin/mappings.vim</code>, using
270 <code>maktaba#plugin#MapPrefix</code> to get a prefix.
271 </SUMMARY>
272 <BODY>
273 <p>
274 All key mappings should be defined in
275 <code>plugin/mappings.vim</code>.
276 </p>
277 <p>
278 Partial mappings (see :help using-&lt;Plug&gt;.) should be defined in
279 <code>plugin/plugs.vim</code>.
280 </p>
281 </BODY>
282 </STYLEPOINT>
283 <STYLEPOINT title="Settings">
284 <SUMMARY>Change settings locally</SUMMARY>
285 <BODY>
286 <p>
287 Use <code>:setlocal</code> and <code>&amp;l:</code> instead of
288 <code>:set</code> and <code>&amp;</code> unless you have explicit
289 reason to do otherwise.
290 </p>
291 </BODY>
292 </STYLEPOINT>
293 </CATEGORY>
294
295 <CATEGORY title="Style">
296 <p>
297 Follow google style conventions. When in doubt, treat vimscript style
298 like python style.
299 </p>
300
301 <STYLEPOINT title="Whitespace">
302 <SUMMARY>
303 Similar to python.
304
305 <br/>
306 <br/>
307 </SUMMARY>
308 <BODY>
309 <ul>
310 <li>Use two spaces for indents</li>
311 <li>Do not use tabs</li>
312 <li>Use spaces around operators
313 <p>This does not apply to arguments to commands.</p>
314 <CODE_SNIPPET>
315 let s:variable = "concatenated " . "strings"
316 command -range=% MyCommand
317 </CODE_SNIPPET>
318 </li>
319 <li>Do not introduce trailing whitespace
320 <p>You need not go out of your way to remove it.</p>
321 <p>
322 Trailing whitespace is allowed in mappings which prep commands
323 for user input, such as
324 "<code>noremap &lt;leader&gt;gf :grep -f </code>".
325 </p>
326 </li>
327 <li>Restrict lines to 80 columns wide</li>
328 <li>Indent continued lines by four spaces</li>
329 <li>Do not align arguments of commands
330 <BAD_CODE_SNIPPET>
331 command -bang MyCommand call myplugin#foo()
332 command MyCommand2 call myplugin#bar()
333 </BAD_CODE_SNIPPET>
334 <CODE_SNIPPET>
335 command -bang MyCommand call myplugin#foo()
336 command MyCommand2 call myplugin#bar()
337 </CODE_SNIPPET>
338 </li>
339 </ul>
340 </BODY>
341 </STYLEPOINT>
342
343 <STYLEPOINT title="Naming">
344 <SUMMARY>
345 <p>
346 In general, use
347 <code>plugin-names-like-this</code>,
348 <code>FunctionNamesLikeThis</code>,
349 <code>CommandNamesLikeThis</code>,
350 <code>augroup_names_like_this</code>,
351 <code>variable_names_like_this</code>.
352 </p>
353 <p>Always prefix variables with their scope.</p>
354 </SUMMARY>
355 <BODY>
356 <SUBSECTION title="plugin-names-like-this">
357 <p>Keep them short and sweet.</p>
358
359 </SUBSECTION>
360 <SUBSECTION title="FunctionNamesLikeThis">
361 <p>Prefix script-local functions with <code>s:</code></p>
362 <p>Autoloaded functions may not have a scope prefix.</p>
363 <p>
364 Do not create global functions. Use autoloaded functions
365 instead.
366 </p>
367 </SUBSECTION>
368 <SUBSECTION title="CommandNamesLikeThis">
369 <p>Prefer succinct command names over common command prefixes.</p>
370 </SUBSECTION>
371 <SUBSECTION title="variable_names_like_this">
372 <p>Augroup names count as variables for naming purposes.</p>
373 </SUBSECTION>
374 <SUBSECTION title="Prefix all variables with their scope.">
375 <ul>
376 <li>Global variables with <code>g:</code></li>
377 <li>Script-local variables with <code>s:</code></li>
378 <li>Function arguments with <code>a:</code></li>
379 <li>Function-local variables with <code>l:</code></li>
380 <li>Vim-predefined variables with <code>v:</code></li>
381 <li>Buffer-local variables with <code>b:</code></li>
382 </ul>
383 <p>
384 <code>g:</code>, <code>s:</code>, and <code>a:</code> must always
385 be used.
386 </p>
387 <p>
388 <code>b:</code> changes the variable semantics; use it when you
389 want buffer-local semantics.
390 </p>
391 <p>
392 <code>l:</code> and <code>v:</code> should be used for consistency,
393 future proofing, and to avoid subtle bugs. They are not strictly
394 required. Add them in new code but don’t go out of your way to add
395 them elsewhere.
396 </p>
397 </SUBSECTION>
398 </BODY>
399 </STYLEPOINT>
400 </CATEGORY>
401
402 <p align="right">
403 Revision 1.1
404 </p>
405
406
407 <address>
408 Nate Soares<br/>
409 Joshua Hoak<br/>
410 David Barnett<br/>
411 </address>
412</GUIDE>