dbarnett@google.com | 4882d60 | 2014-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 |
| 200 | <a href="http://goo.gl/CUXJZC">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 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> |