關於 web service, unity, blogger 等軟體工程筆記

C# coding style 檢查工具 - StyleCop

Edit icon 沒有留言
StyleCop

Coding style,程式寫作風格,每個人寫作風格都有所不同,例如變數命名大小寫,函數大括號需不需換行,使用 space 還是 tab 來縮排等等。

在多人的大專案中,會期望成員們使用相同的寫作風格,以讓其他成員們容易互相支援,維護程式碼。

但怎麼確認有按照規定的 coding style 撰寫呢?同儕回顧 (Peer review) 會是一個好方式,但需要花人工檢查,是一個煩雜的工作,且人偶爾會出錯,不一定能確認完全遵守規則。因此如果若有檢查的工具會比較方便。

紀錄使用 StyleCop 的操作筆記,以利之後團隊成員的教學使用。

StyleCop

StyleCop,依附在 Microsoft Visual Stuido 下的一套 coding style 檢查工具,可以協助檢查目前開啟專案的 C# 程式碼,是否有符合所設定的檢查規則。這些規則也可以根據團隊需要,決定那些規則需要套用檢查,自訂團隊的 coding style rules。更重要的是,StyleCop 是免費工具。

從官方網站 StyleCop-Home 下載安裝後,重新啟動 Visual Studio 後,便可點擊 Menu > Tools > Run StyleCop (或是快捷鍵 Ctrl+Shift+Y),執行專案的 coding style 檢查。

在 Visual Studio 中執行 StyleCop 檢查

花費一些時間跑完後,便可以在 ErrorList 看到這些不符合當前規則 (SAxxxx) 的警告:

StyleCop 結果

編輯 StyleCop 檢查規則

開啟 Source Explorer (Menu > View > Source Explorer,或是快捷鍵 Ctrl + Alt + L),點選 Project node,滑鼠右鍵 (right click),開啟 StyleCop Settings:

開啟 StyleCop 設定視窗

在這視窗中任意調整所需要的 coding style rules:

StyleCop 設定調整視窗

當編輯完檢查條件後,在專案檔資料夾會多出 Settings.StyleCop 檔案,紀錄那些規則需要套用,將該檔案上傳至版本控制伺服器 (e.g. Git),便可與他人共享相同的規則進行檢查。

關於這些規則的說明,請參考 官方文件 Wiki,共七大項的規則。

分享我們之前設定規則的方式,我們並沒有看完全部規則後才開始設定,而是對現有專案直接執行 StyleCop,根據檢查結果一個一個去了解,目前有哪些規則不符合,然後再討論要不要遵循這規則。

例外處理

有時候會遇到不能符合規則的程式寫法,可能是設計架構不得不的寫法,在不改動 StyleCop 規則情況下,要讓程式碼不提示 coding style 不符合的警告,就可以使用例外 attribute:

[SuppressMessage("Rule Category", "Rule Id", "Justification")]

例如針對自定義 property 名稱開頭必須大寫的例外:

using System.Diagnostics.CodeAnalysis;

[SuppressMessage("Microsoft.StyleCop.CSharp.NamingRules", "SA1300:ElementMustBeginWithUpperCaseLetter", Justification = "for Unity API, reviewed")]
public override Texture mainTexture
{
   get { ... }
}

更多細節請參考官方文件:Suppressions

自訂規則

StyleCop 支援自訂規則檢查,利用 C# 撰寫檢查規則的程式碼,目前還沒有機會自寫規則,細節請參考官方文件:Writing Custom Rules for StyleCop

結語

未來可以嘗試與 CI 伺服器整合 (e.g. Jenkins),當版本上傳更新後,自動執行 StyleCop 規則檢查,若規則檢查沒有通過,寄出信件團隊,提醒團隊需要調整程式碼,讓專案程式碼維持相同的 coding style,確保一致性寫作風格的程式碼。

沒有留言: