沒穿方服

---

不要用簡寫

指的是選項、指令名稱的簡寫，例如：

• function! → fun!
• setlocal textwidth=78 → setl tw=78
• execute "normal! dd" → exe "norm! dd"

例子可能不夠極端（還是看得懂），但是已經失去字面上的意思（最簡單的可讀）了。

此外還有一致性的問題，完全一樣的意思卻不能預期用哪個敘述。
例如想找函數定義，直接搜尋 func! 卻找不到 function!，問題是什麼？ 其實不必問了，這完全是可以避免的問題。

總之除非有足夠理由（例如故意用 fun! 定義比較 funny 的函數），還是一律用完整寫法吧。

---

在 modeline 寫明縮排規則

縮排和可讀性的關係是，縮排亂掉的時候會很難讀。

首先要訂好自己的縮排規範，用空白還是 Tab、要空幾格，然後確實遵守。
再來要了解每個人的規則會不一樣：

• 你用 Tab 排好的版，別人打開還是可能亂掉。
• 別人編輯你的 script 後，可能也塞了不一致的縮排字元進去。

減輕問題的方式是在每個檔案加上 modeline：
例如一律用空白，確保排版不會被 Tab 弄亂
" vim: expandtab softtabstop=2 shiftwidth=2
如果還是偏好 Tab（也許為了減少字數）
" vim: noexpandtab tabstop=8 shiftwidth=8

附上我的基本 modeline 如下（寫在檔案最後一行）

" modeline {{{
" vim: expandtab softtabstop=2 shiftwidth=2 foldmethod=marker

---

用 marker 手動折疊程式碼，建立 section

在註解中使用 marker（預設是 {{{ 和 }}}）整理程式碼是很普遍的作法， script 稍大時幾乎都會用上，否則會覺得難爬。

對以下常見的 folding：

1. 多個有關的函數，可以歸納為一個 section（註：和 Vim motion 的 section 無關），但是沒什麼好方法表示，於是加上註解「以下這段是做 XXX」，然後在結束的地方寫「XXX 做完了」。這整段就適合當作一個 fold
   
2. 讓多次出現的語法單位（通常就是函數）可以各自折疊

規範一個通用的格式。

以下是我的例子。 從 Utils: 開始是一個叫做 Utils 的 section，用大寫字和冒號形成一個 vimCommentTitle（來自預設的 syntax 上色），又更顯目一點。

" Utils: {{{

function! s:save_reg(name) "{{{
  let s:save_reg = [getreg(a:name), getregtype(a:name)]
endfunction "}}}

function! s:restore_reg(name) "{{{
  if exists('s:save_reg')
    call setreg(a:name, s:save_reg[0], s:save_reg[1])
  endif
endfunction "}}}

" }}} Utils

折起來（一層）後，擷圖如下

---

增加空行，分隔程式區塊

• 函數之間，空 2 行。
  因為函數中本來就經常會空 1 行，所以要空超過 1 行才清楚。
• section 之間，空 2 行。
  這裡 2 行就夠了，因為 marker（在註解中）和程式之間也有空行，所以不算註解的話，實際上 section 之間會空 6 行。

全部縮起來（zM）時，看見所有 section

打開一個 section，看見所有 function

抱歉擷圖是舊程式，函數之間只空 1 行，應該空 2 行……

各個 function 之間空兩行

各個 section 之間空兩行，實際程式空了 6 行

---

註解不應影響程式排版

手動 fold 有很多層的時候，我曾經把深層的程式加一級縮排：

" MAPPINGS             {{{1 ==================================================

  let maplocalleader = ","
  noremap  <Leader><LocalLeader> <LocalLeader>

  "   各種移動    {{{2

    noremap <expr> <Space>  repeat('<ScrollWheelDown>', 2)

看起來似乎更清楚，但這個超過註解該做的事了。
理想上要專注於程式本身的表達能力才對。

---

串接多個項目時，拆成多行

寫下 aaa, bbb, ccc, ... 這樣的敘述時，除非真的很簡單，否則不要擠在同一行，難讀又難改。

• 參數很多時
• 定義複雜的 List (Array) 或 Dictionary (Hash) 時

請用 backslash (\) 拆開。

call setline(
      \   a:before.line,
      \   substitute(
      \     getline(a:before.line),
      \     '\%' . a:before.col . 'c' . s:escape_pattern(a:before.text),
      \     s:escape_sub_expr(a:after.text),
      \     ''
      \   )
      \ )

這裡的縮排比較詭異，不是由 indent 選項而是由一個變數控制，見 ft-vim-indent，預設是 shiftwidth 的三倍。
let g:vim_indent_cont = &shiftwidth * 3
我沒有設這個變數，backslash 之後的縮排也是手動做的，規則是至少空一格，其餘每一層就縮一級。
單純是「採用預設值」這個考量。

---

適當使用 Dictionary (hash) 進行參數操作

可以考慮多用 hash（Vim 裡面叫 Dictionary）作為函數的參數，例如原本是：
function Img(src, alt, size, class) 或接受任意個參數的
function Img(src, alt, size, ...) 都可以改成
function Img(src, options)
就不必記參數的順序，或再解析 a:0、a:1（額外的參數會被轉成 a:N）了。

存取 options 的時候，盡量用點（.）取代方括號（[]），
例如 options.size 就比 options['size'] 簡單明瞭。

不過因為 Vim script 的特性，也有一些像陷阱的東西。
例如取值的時候要用 get(options, 'size') 比較安全，沒有 'size' 這個 key 的時候才會回 0，而不是報錯。
還有在 value 不是 Number 時，直接 if get(options, 'key') 會有型別轉換的細節要注意， 通常會加一道 if type(get(options, 'key')) == type(xxx) 檢查，比較麻煩。

---

其他相關但未規範的部分

• 單行的長度

  要填滿整行的話，會用 textwidth=78，和 Vim doc 一樣。
  但是程式內文就不必了，因為怕太長其實是硬體問題，我認為不用管它，也解決不了它。

• 變數命名

  Vim 對變數名稱有一些意見，例如 user function 第一個字要大寫，大小寫變數存進 session 時的規則也不同。
  原則上使用 underscore_names 安全又簡單，可惜有時候必須大寫，還是會破例。

  具體用字則是愈短、愈直接愈好，scope、autoload 和 Dictionary 可以善加利用，
  例如 s:width、su#do()、contribute.till_die。

• key mapping 的記法

  原則是和 Vim doc 一致，也就是用 <C-X> 而不用 <C-x>。
  不過這樣會失去大小寫的區別。

• Magic 的 regexp

  Vim 的 regexp pattern 對哪些字元有特殊意義（需要跳脫）和別家解釋不太一樣， 在 pattern 前加上 \v \m \M \V 又有不同解讀， 在 plugin 或一些內建 function 裡還會一律視為 \m。

  這個因應情境有很多變數，所以目前也沒有規範。