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 200 <a href="https://github.com/MarcWeber/vim-addon-manager/blob/master/doc/vim-addon-manager-additional-documentation.txt">VAM documentation</a> for details). 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-<Plug>.) 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>&l:</code> instead of 288 <code>:set</code> and <code>&</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 <leader>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 dont 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> 413
