Allen 技術筆記

1. 命名規則

閱讀時間約 19 分鐘

命名規則(Naming Rule)

簡介命名規則

本文件旨在闡述並制定一套完整、清晰的資料庫物件命名標準。制定此份規範的核心目的，在於透過標準化命名來大幅提升團隊的協作效率、程式碼的可讀性以及系統的長期可維護性。一個一致且可預測的命名系統，是降低溝通成本、避免誤解、加速新成員融入專案的關鍵基石，對於控制長期開發與維護成本具有無可取代的戰略重要性。

本文件將作為專案開發過程中，所有資料庫相關工作的核心參考依據，所有團隊成員均須嚴格遵循。我們的目標是共同建立一個結構清晰、邏輯一致、易於理解與管理的資料庫環境。

  1. 通用命名原則
    本章節將定義所有資料庫物件（包括 資料表、欄位、索引、預存程序 等）都必須共同遵守的基礎命名規則。這些規則是構建一個專業、穩定且清晰資料庫結構的基石，為後續的具體規範提供了統一的語法基礎。

    所有物件的命名都必須遵循以下最基本的語法要求：

    遵循這些通用原則是確保資料庫結構一致性的第一步。接下來，我們將深入探討針對不同類型資料庫物件的詳細命名規範。

資料表格 (Table) 命名規範

資料表格是資料庫的骨架，其命名方式直接影響著整個系統的設計藍圖。一個良好且可預測的表格命名系統，不僅能讓資料庫結構一目了然，更能顯著簡化後端應用程式（特別是 ORM 框架）與資料庫之間的映射關係，提升開發效率。

  1. 核心命名慣例
    為了確保專案內部風格統一，所有資料表格的命名應從以下幾種業界常見的風格中擇一使用，並在專案啟動初期確立為團隊共同標準。

    • 蛇形命名法 (Snake Case)：
      所有字母小寫，單字之間使用底線 _ 分隔。此風格清晰易讀。
      範例： order_detail
    • 帕斯卡命名法 (Pascal Case)：
      每個單字的首字母大寫，不使用分隔符。
      此風格常與物件導向程式語言的類別命名保持一致。
      範例： OrderDetails
    • 全大寫蛇形命名法 (All Caps Snake Case)：
      所有字母大寫，單字之間使用底線 _ 分隔。
      此風格通常用於強調常數或系統核心表格。
      範例： ORDER_DETAIL

    重要提示
    團隊必須在專案初期統一選擇其中一種風格，並在整個專案生命週期中貫徹執行，以維持命名的一致性。

  2. 模組化命名法

    在大型或複雜的企業級系統中，採用模組化命名是一種極具價值的策略。透過在表格名稱前加上代表業務領域的模組代號前綴，可以快速識別資料表所屬的功能模組，有效避免不同模組間可能出現的命名衝突，並使資料庫結構更具組織性。

  3. ASP.NET Core 開發環境實踐指南
    考量到與現代開發框架（特別是 ORM 工具如 Entity Framework Core）的無縫整合，我們為 ASP.NET Core 開發環境提供以下命名實踐。

    規定
    在此開發環境中，統一採用以下命名規則：
    首字大寫的帕斯卡命名法 (PascalCase)，並統一使用能代表實體集合的複數形式。

    資料表的命名是資料庫設計的藍圖。在定義了宏觀的表格結構後，我們需要進一步規範構成表格的基礎單位——欄位的命名。

欄位 (Field) 命名規範

欄位命名是資料庫設計中最細緻也最關鍵的一環。精確、一致的欄位命名能大幅提升 SQL 查詢的可讀性，從根本上減少因資料誤解而導致的程式錯誤，並顯著加速開發人員對資料模型的理解與應用。

  1. 核心命名慣例
    與資料表命名類似，欄位命名也應遵循一致的風格。團隊可根據專案特性選擇以下組合：

    • 大小寫風格： 可選擇 全部小寫 (snake_case)、全部大寫 (SNAKE_CASE) 或 首字大寫 (PascalCase)。

    • 命名長度： 應在 全名 (例如 quantity) 與 標準簡寫 (例如 qty) 之間做出統一選擇，以保持平衡的可讀性與簡潔性。

  2. 標準欄位縮寫詞典
    為了確保在整個資料庫中，相同業務概念的欄位使用完全一致的名稱，避免出現如 Qty , Quantity , Amount 等混用的混亂情況，我們建立了以下官方縮寫詞典。
    所有開發人員在命名相關欄位時，必須優先參考此表。

  3. 特定實體欄位命名
    為了確保核心業務實體（如 客戶、產品 等 主檔 資料，以及 訂單、發票 等 表單檔 資料）的結構一致性與可預測性，我們特別定義了一組標準欄位名稱。所有屬於這兩類實體的資料表，都應優先使用以下標準欄位。


    表單 (Transaction Form) 標準欄位

    欄位名稱說明
    SheetNo單據編號
    SheetDate單據日期
    SheetCode單據類別
    TargetNo對象代號
    SourceNo來源編號
    TransferNo拋轉編號
    TaxCode稅別
    CurrencyNo幣別
    ExchangeRate匯率
    CloseMonth結帳月份
    SheetAmount未稅金額
    SheetTax稅額
    SheetTotal已稅金額
    IsConfirm確認
    IsClose結案
    IsInvalid作廢
    ParentId父階ID

    重點提示
    名稱以 Is 為前綴的欄位，其用途為布林值（是/否）標記。

    在定義了資料表與欄位的命名規範後，我們還需將此標準擴展至其他輔助性的資料庫物件，以確保整體結構的完整與一致。

其他資料庫物件命名規範

除了核心的資料表和欄位，資料庫中還包含 檢視 (View)、觸發程序 (Trigger)、預存程序 (Store Procedure)、索引 (Index) 等重要物件。為這些物件建立一套基於前綴的命名系統，可以讓開發者在瀏覽資料庫結構或閱讀 SQL 腳本時，能夠立即識別出物件的類型和用途，極大化地提升資料庫的管理與維護效率。

所有非資料表/欄位的物件，都應根據其類型，採用以下前綴進行命名。

所有資料庫物件都應被納入此命名體系，共同構建一個全面標準化、高度透明的資料庫環境。

不好的命名規則

  1. 不好的命名規則範例



  2. 問題說明
    在你學習語法和演算法的同時，有一個基礎但極其重要的觀念需要建立：寫程式不只是為了讓電腦看懂，更重要的是讓人（包括未來的自己和同事）看懂。

    想像一下，你拿到一個沒有標籤的藥罐，只寫著代號「US001」。你敢吃嗎？你必須去翻閱一本厚厚的說明書，才能查出它到底是什麼。程式碼的命名也是如此。當我們使用像 TRTUS 或 US001 這樣無意義的表格命名時，就會引發一系列嚴重的問題，讓維護系統變成一場災難。接下來，我們將逐一拆解這些問題。

  3. 喪失「自我描述」能力，逼你隨時查字典
    在現代軟體工程中，有一個核心原則叫做 「程式碼即文件 (Code as Documentation)」。這意味著好的程式碼應該像一篇清晰的說明文件，光是閱讀名稱就應該能大致理解其用途。

    然而，當我們使用像 TRTUS 和 US004 這樣的代碼時，程式碼就徹底喪失了自我解釋的能力，變成了一個需要 「解碼」 的 「黑盒子」。根據資料顯示，工程師在維護這樣的系統時，完全無法從名稱猜出其含義，必須依賴一份外部的 Excel 「對照表」 才能知道：

    對照表
    TRTUS 原來是「請假資料明細檔」。
    US004 代表的是「請假人員」。

    ⚠️ 注意：外部文件的致命弱點
    這種工作流程的風險極高。如果這份關鍵的 Excel 對照表遺失、版本落後，或是有人修改了卻沒有及時更新，整個系統將變得幾乎無法維護。開發者會像在沒有地圖的迷宮中行走，寸步難行。

    這種對外部文件的依賴不僅麻煩且充滿風險，更會在系統的不同部分產生命名混淆，進一步加重開發者的腦力負擔，引出下一個問題。

  4. 增加「認知負擔」，讓你陷入記憶陷阱
    開發者的 「認知負擔」 指的是在工作時，需要花費腦力去記憶、追蹤和理解程式複雜性的程度。不好的命名會急遽增加這種負擔，讓你像在玩一場困難的記憶力遊戲。

    問題的根源在於命名缺乏一致性。例如，同一個業務概念在不同的資料表中，被賦予了完全不同的代碼，造成了嚴重的混亂。

    業務概念資料表 A (TRTUF) 的命名資料表 B (TRTUS) 的命名
    請假單號UF001US002

    從上表可以看出，明明都是「請假單號」，在兩張關聯的資料表中卻有不同的名稱。這迫使開發者在撰寫資料庫關聯查詢（JOIN）時，被迫寫出如下這樣違反直覺的程式碼：

    WHERE TRTUF.UF001 = TRTUS.US002

    這種對應關係毫無邏輯可言，開發者只能靠死記硬背。這極度容易因為記錯編號而導致嚴重的資料串接錯誤，進而引發難以追查的系統 Bug。這種做法完全違背了「意圖導向命名 (Intention-Revealing Names)」這個現代軟體工程原則。好的命名應該是直觀且一致的，例如

    WHERE Header.ID = Detail.HeaderID

    讓人一眼就能看懂其關聯意圖。

    這種混亂不僅僅存在於資料庫的結構層面，它還會進一步滲透到程式碼的商業邏輯判斷中，催生出大量的「魔法咒語」。

  5. 可讀性極低
    你是否在程式碼中見過一些突然冒出來、沒有任何解釋的數字或字串？它們被稱為「魔術數字 (Magic Numbers)」或「魔術代碼」。它們就像咒語一樣，只有當初寫下它的人才知道其真實含義。

    在一個充滿無意義代碼的系統中，程式碼的商業邏輯會變得極其晦澀。如果沒有註解或對照文件，維護者完全無法理解這段程式碼的意圖。

    // 範例：判斷請假單狀態
IF US009 == '1' THEN
// ... 執行請假相關邏輯

    看到 US009 == '1'，你能猜到這是什麼意思嗎？

    經過查閱外部文件後，我們才能將這些「魔法咒語」翻譯成人類可讀的業務邏輯：

    • US009（狀態碼）：1 代表 請假，2 代表 銷假，3 代表 抽單`。
    • UF012（親屬關係）：1 代表 父，2 代表 母`。

    這個版本的優點顯而易見：程式碼不言自明，可讀性極高，任何開發者都能立刻理解其商業邏輯，無需再查閱任何外部文件。

    這種混亂的命名方式不僅嚴重影響了程式碼的可讀性，還會從根本上破壞資料本身的邏輯結構，引出最後一個災難性問題。

  6. 結構僵化
    在軟體設計中，有一個重要的原則叫做「高內聚 (Cohesion)」，意思是相關的資料或功能應該在結構上被組織在一起。然而，流水號式的命名方式會徹底破壞這種內聚性，讓資料表變成一個雜亂無章的倉庫。

    由於欄位名稱是流水號（如 UF001, UF002…），當需要新增欄位時，唯一的做法就是不斷地在後面追加新的號碼。這導致新欄位不是按照業務邏輯分組，而是按照「修改歷史」不斷向後堆疊。在專案資料中可以發現，資料表的結構真實地反映了這種混亂的開發過程：

    • 欄位 UF015 到 UF019 被標註為 —> TONY 新增
    • 欄位 UF020 到 UF023 被標註為 Benson

    這種做法的直接後果是，資料表的結構反映的不再是「這些資料代表什麼」，而是「誰在什麼時候加了什麼」。這會導致本應屬於同一個業務概念的欄位（例如與審核流程相關的所有欄位）被分散在資料表的頭尾各處，讓後續的維護者極難理解資料的全貌，也讓系統的重構變得異常困難。

    綜合以上問題，它們共同指向了一個災難性的結果：開發團隊的精力被嚴重浪費在無效的工作上。

總結與遵循要求

本規範的制定與執行，是確保我們軟體專案品質與長期健康發展的關鍵舉措。嚴格遵循這些標準不僅是一項技術要求，更是團隊專業素養、協作精神與工程紀律的直接體現。一個乾淨、一致的資料庫是高效能應用的基礎。

對所有團隊成員提出以下具體要求：

  • 強制遵循：
    所有新的資料庫設計、開發以及修改工作，都必須嚴格遵守本文件所定義的規範。
  • 程式碼審查：
    在進行資料庫相關的程式碼審查（Code Review）時，應將命名規範的符合性作為一項重要的檢查標準。任何不符合規範的提交都應被標記並要求修改。
  • 動態文件：
    本規範是一份「動態文件」，將隨著專案的發展和技術的演進持續更新。團隊成員有責任保持對最新版本規範的了解與遵循。

讓我們共同努力，維護一個高品質、高效率、高可維護性的資料庫環境，為專案的成功奠定堅實的基礎。

關係圖譜