asp.net core web api model naming rule coding style appsettings visual studio code restful api

ASP.NET Core 5 EP 4:Naming Rule & Coding Style

命名大原則 (Naming Rule)

  • 通用的字詞
    避免使用艱澀的文字,如學名、拉丁文、拼音或專有名詞等,縮寫也盡量避免。
  • 有意義的字句組合
    讓人一看就知懂,不需要猜測或產生誤解。
  • 動詞、名詞為主
    動作就用動詞,物件用名詞,避免使用形容詞,因爲程式是對一個明確的目標做動作。
  • 區別單、複數
    若是某一種集合,字尾加一個s,以複數表示,否則以單數命名。
  • 一貫的大小寫規則
    駝峰式命名法是最常見的,盡可能依照規則。
  • 變數以明確的型態標註
    命名變數時,可以將型態作為變數名稱的前置詞,不要使用my開頭。

區分程式碼目錄

以本系列要撰寫一個食譜的API服務來說,將會用到的程式碼分為邏輯運算、通用程式、資料模型與控制器四種,除了在本質上的區分外,也應該將他們放在不同的目錄中,不只是便於管理,也讓後續維護更為簡單,這對應到上一篇設計目錄的部分,其對應如下:

#程式本質目錄(資料夾)
1邏輯運算Libs
2通用程式Commons
3資料模型Models
4控制器Controllers

註釋

通常在幾個地方會寫下註釋,包括:

  • 每個程式碼檔案的標頭,說明這個程式碼檔的用途與基本資訊。
  • 變數宣告,描述變數的目的及用法。
  • 函數,說明函數的用途、輸入與輸出。
  • 邏輯運算程式碼,解釋較不易看懂的程式碼,讓程式碼更易於瞭解。

定義標準的Log格式

一般Log的格式包含一定要包含三個W元素:When、Where、What,在IT的世界分別是:

  • 時間:以一致的格式標註事件發生的時間,如yyyy-MM-dd HH:mm:ss.fff。
  • 主機:使用主機名稱來定位發生地點,通常也可以包含網址或程式碼的位置。
  • 事件:描述事件內容,如資料庫無法連線、除0…等,寫得越清楚越有利於後續的Debug。

其他

程式撰寫風格內容包羅萬象,大部分具規模的公司都會有自己一套規範,甚至不同語言也會有不同的設計,大家可以依據以上的內容出具一份自己的命名規則與程式風格的說明書。

~ END ~


, , ,

Related posts

Latest posts