Copyright © 2008 ~ 2024 MUKI space* / omegaBook theme All Rights Reserved.

起源

最近功能寫得愈來愈複雜,為了避免「幾天後回頭看,看不懂自己在寫啥」的窘境,決定認真規範自己的註解結構。

因此我在 VS CODE 搜尋了一下,想看看有沒有什麼好用的註解套件?

最後選擇了這兩款:

  • Better Comments:爆多人用的,應該是人手一裝了 XD
  • Todo Tree:雖然下載數輸 Better Comments 一點,但一樣有百萬安裝量

用了之後真是驚為天人,很驚訝自己沒早點發現 艸。

這邊也記錄一下自己的設定跟使用的方法,供大家參考!

延伸閱讀

如果想知道我安裝了哪些 VS CODE 套件?用了什麼佈景主題?歡迎參考我之前寫的文章

Better Comments

特色

Better Comments 可以高亮註解。原理是根據你設定的前綴詞,有不同的高亮效果。

▼ 安裝後有預設的顏色與前綴詞,以下是官方提供的效果

我的高亮設定檔

▼ 這是我自己修改後的高亮效果

▼ 我的 Better Comments 設定檔

"better-comments.tags": [
    {
      "tag": "!",
      "color": "#d9444a",
      "strikethrough": false,
      "underline": false,
      "backgroundColor": "transparent",
      "bold": true,
      "italic": false
    },
    {
      "tag": "?",
      "color": "#f5c018",
      "strikethrough": false,
      "underline": false,
      "backgroundColor": "transparent",
      "bold": false,
      "italic": false
    },
    {
      "tag": ">",
      "color": "#fff",
      "strikethrough": false,
      "backgroundColor": "transparent"
    },
    {
      "tag": "-",
      "color": "#6D8CB4",
      "strikethrough": false,
      "backgroundColor": "transparent"
    },
    {
      "tag": "//",
      "color": "#474747",
      "strikethrough": true,
      "underline": false,
      "backgroundColor": "transparent",
      "bold": false,
      "italic": false
    },
  ],

我的註解結構

// - 一般的註解

// ! 比較複雜的、我回頭再看可能會忘記的邏輯或功能說明

// ? 需要與其他協作者溝通的留言

// > 目錄索引 (多用於 CSS 檔)

// // 沒用卻要備份的程式碼

這邊特別將「> 目錄索引」拉出來分享,我自己設計完覺得還蠻好用的,也許會對在寫 CSS 的各位有幫助。

我們在寫 CSS 時,很容易在一個檔案裡寫了非常多的語法,當語法一多,要找資料就變得很困難。

▼ 在還沒有使用 Better Comments 前,我是這樣幫 CSS 檔案做整理的

/* ==========================
1. 功能介紹一 <<< HERE
2. 功能介紹二
3. 元件樣式
=============================*/

.a { }
.b { }
.c { }

/* ==========================
1. 功能介紹一 
2. 功能介紹二 <<< HERE
3. 元件樣式
=============================*/

#a { }
#b { }
#c { }

我在每一段功能的前面加入的註解與「<<< HERE」的索引,對我來說,打開一個檔案就可以清楚知道裡面有哪些 CSS 功能,還有我目前是在哪一層。

雖然每次新增功能,都要重複編輯註解,但對我來說還算堪用。

▼ 現在有了 Better Comments 之後,我改用以下寫法

/* ==========================
> 1. 功能介紹一
2. 功能介紹二
3. 元件樣式
=============================*/

.a { }
.b { }
.c { }

/* ==========================
1. 功能介紹一 
> 2. 功能介紹二
3. 元件樣式
=============================*/

#a { }
#b { }
#c { }

<<< HERE 改成前綴詞 >,這一整行就會變成白色,我可以更清楚的知道現在在哪個位置。

以上就是我使用 Better Comments 的方法,如果你們有更棒的使用方法,歡迎留言告訴我!


Todo Tree

我覺得 Todo Tree 的功能更強大,它包含了 Better Comments 的高亮,此外還能管理我們設定的這些前綴詞唷。

使用介紹

Todo Tree 預設有三種前綴詞,分別是:TODO, FIXME, BUG,只要在註解前面加入這些前綴詞,一樣能有高亮設定。

▼ 以下是我修改後的樣式

▼ 而 Todo Tree 另一個強大的功能,是能將這些前綴詞集合起來管理,點選註解,就會跳到對應的檔案,將這些註解變成方便管理的待辦事項!而 Todo Tree 把這功能稱之為「Tree」。

結合 Todo Tree 與 Better Comments

既然 Todo Tree 也有註解高亮的功能,是否能將 Better Comments 的設定一起整合進來呢?

答案是可以!

因為 Todo Tree 可以設定,哪些註解要進「Tree」,哪些要隱藏,因此我們前面設定的註解,不一定都要在「Tree」中顯示,自由度非常高。

目前兩個套件在設定上比較顯著的差別是,Better Comments 可以為註解設定「粗體」以及「刪除線」,而 Todo Tree 我目前沒找到這個功能(如果有再請各位大大留言告訴我)。

因此,如果你不介意有沒有刪除線,那這兩個套件只要選一個用就行了,我自己最後是選擇 Todo Tree,捨棄 Better Comments。

我的 Todo Tree 設定檔

記得要新增 tag 之前,都要先將 tag 加到 todo-tree.general.tags 喔!

如果不想在「Tree」顯示 tag,就在設定檔加入 "hideFromTree": true 即可。

▼ 我的 Todo Tree 設定檔

"todo-tree.general.tags": ["-", "!", "?", ">", "TODO","FIXME"],
"todo-tree.highlights.customHighlight": {
  "-": {
    "background": "#222",
    "foreground": "#6D8CB4",
    "iconColour": "#6D8CB4",
    "icon": "check",
    "type": "text-and-comment",
    "hideFromTree": true
  },
  "!": {
    "background": "#222",
    "foreground": "#d9444a",
    "iconColour": "#d9444a",
    "icon": "check",
    "type": "text-and-comment",
    "hideFromTree": true
  },
  "?": {
    "background": "#222",
    "foreground": "#f5c018",
    "iconColour": "#f5c018",
    "icon": "check",
    "type": "text-and-comment",
    "hideFromTree": true
  },
  ">": {
    "background": "#222",
    "foreground": "#fff",
    "iconColour": "#fff",
    "icon": "check",
    "type": "text-and-comment",
    "hideFromTree": true
  },
  "TODO": {
    "background": "#f5c018",
    "foreground": "#000",
    "iconColour": "#f5c018",
    "icon": "check",
    "type": "text-and-comment"
  },
  "FIXME": {
    "background": "#d9444a",
    "foreground": "#000",
    "iconColour": "#d9444a",
    "type": "text-and-comment"
  }
},

▼ 我的所有註解高亮設定

Status Bar 功能

除了有一整個「Tree」選單外,Todo tree 還能在底部的狀態列,顯示 tags 的數量與狀態。

todo-tree.general.statusBar 預設為 none(不顯示),我們可以選擇 total, tags, top three, current file 這四個屬性。

"todo-tree.general.statusBar": "tags",

▼ 出現在底部狀態列

進階設定

Todo tree 可以設定的功能非常多,有興趣的朋友可以看他的官方文件:https://marketplace.visualstudio.com/items?itemName=Gruntfuggly.todo-tree

歡迎給我點鼓勵,讓我知道你來過 :)

13
20
1
1
Subscribe
Notify of
guest

0 則留言
Inline Feedbacks
View all comments