[Tools] 使用 GhostDoc 自動產出符合語意的註解

2016-01-21

3116
0
Tools
2016-01-21

是否有為了寫註解而寫註解的困擾呢?

可以考慮使用 GhostDoc 幫忙自動補上合乎語意的註解。

前言

對於寫註解這件事情來說，有時候真的是為了寫而寫，有可能 Method 名稱已經說明了一切，但是為了要產出交付客戶的 API 文件，只好硬著頭皮去寫一堆重複敘述的註解；其實這樣寫實在是很浪費時間，所以本篇文章要介紹如何使用 GhostDoc 來自動產出符合語意的註解。

環境

Visual Studio 2013
GhostDoc 5.0.15325

安裝

請至官方網站下載安裝，本篇文章是使用免費版本 GhostDoc 進行說明

支援 Visual Studio 2008 ~ 2015 全系列

注意事項

其實自動產出註解的原理就是透過 Method 與 Parameter 名稱，將常見的命名慣例套至預設註解 Pattern 中，進而產生符合語意的註解。因此需要注意以下命名事項，才可產生更符合語意之註解 (比較不用再去手動調整啦)

代碼使用Pascal或Camel命名 ex. CreateDefaultUserInstance()
語意要清楚 ex. IsValid, HasError
盡量避免使用不通用之縮寫

實際演練

使用的方式相當簡單，只要在 Method 或是屬性等等上方按下 Ctrl + Shift + D，註解就會自動產出；以下自動產出的註解語意是相當接近我們所需的，剩下的只需再次審視該註解是否合乎需求。另外，此方法帶來的周邊效益就是可以讓專案內註解的 Style 一致，減輕後續維護人員的負擔。