最近在寫 plugin,對之前的 coding style(主要用在 vimrc)有些不同意了。
其中一些比較確定、通用的部分是關於可讀性的,整理如下:

  1. 不要用簡寫
  2. 在 modeline 寫明縮排規則
  3. 用 marker 手動折疊程式碼,建立 section
  4. 增加空行,分隔程式區塊
  5. 註解不應影響程式排版
  6. 串接多個項目時,拆成多行
  7. 適當使用 Dictionary (hash) 進行參數操作
  8. 其他相關但未規範的部分

不要用簡寫

指的是選項、指令名稱的簡寫,例如:

  • function!fun!
  • setlocal textwidth=78setl 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

全部縮起來(zM)時,看見所有 section

打開一個 section,看見所有 function

抱歉擷圖是舊程式,函數之間只空 1 行,應該空 2 行……
打開一個 section,看見所有 function(抱歉擷圖是舊程式,函數之間只空 1 行,應該空 2 行)

各個 function 之間空兩行

各個 function 之間空兩行

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

各個 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:0a: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:widthsu#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。

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