diff --git a/_includes/sqlstyle.guide.zh-TW.md b/_includes/sqlstyle.guide.zh-TW.md index fdbefb5..62f42ff 100644 --- a/_includes/sqlstyle.guide.zh-TW.md +++ b/_includes/sqlstyle.guide.zh-TW.md @@ -1,27 +1,27 @@ # SQL style guide SQL樣式指南 -這篇文檔翻譯自以[署名-相同方式共享 4.0 國際協議][licence-zh]發布的[http://www.sqlstyle.guide][sqlstyleguide],譯文以原文同樣的協議發布。 +這份文件翻譯自以[創用 CC 姓名標示-相同方式分享 4.0 國際 授權條款][licence-zh]發布的[http://www.sqlstyle.guide][sqlstyleguide],譯文以原文同樣的條款發布。 ## Overview 綜述 -你可以直接使用這些指導方針,或者[fork][fork]後創建自己的版本——最重要的是選擇一套方針並嚴格遵守它。歡迎通過提交[issue][issue]或[pull request][pull]來提交建議或修覆bug。 +你可以直接使用這些指導方針,或者[fork][fork]後創建自己的版本——最重要的是選擇一套方針並嚴格遵守它。歡迎通過提交[issue][issue]或[pull request][pull]來提交建議或修復bug。 -為了讓閱讀了Joe Celko的《[SQL ProgrammingStyle][celko]》的團隊能更容易采用這套規則, 這套原則被設計成與該書的兼容的形式。該指南在某些領域嚴格一些,在另一些領域松懈一些。 當然該指南比Celko的書更簡潔一些,因為Celko的書包含了一些趣聞和每一條原則後的理由。 +為了讓閱讀了Joe Celko的《[SQL ProgrammingStyle][celko]》的團隊能更容易采用這套規則,這套原則被設計成與該書的型式相容。本指南在某些領域嚴格一些,在另一些領域寬鬆一些。 當然本指南比Celko的書更簡潔一些,因為Celko的書包含了一些趣聞和每一條原則背後的理由。 -將該文檔的[Markdown format][dl-md]格式添加到項目代碼庫中或將該頁面的鏈接發送給所有項目的參與者要比傳閱實體書容易得多。 +將此文檔的[Markdown format][dl-md]格式添加到專案程式庫中或將該頁面的鏈接發送給所有項目的參與者要比傳閱實體書容易得多。 -[Simon Holywell][simon]所著的《SQL樣式指南》以[署名-相同方式共享 4.0 國際協議][licence-zh]發布,改編自[http://www.sqlstyle.guide][sqlstyleguide]。 +[Simon Holywell][simon]所著的《SQL樣式指南》以[創用 CC 姓名標示-相同方式分享 4.0 國際 授權條款][licence-zh]發布,改編自[http://www.sqlstyle.guide][sqlstyleguide]。 ## General 一般原則 ### Do 應該做的事情 * 使用一致的、敘述性的名稱。 -* 靈活使用空格和縮進來增強可讀性。 -* 存儲符合[ISO-8601][iso-8601]標準的日期格式(`YYYY-MM-DD HH:MM:SS.SSSSS`)。 -* 最好使用標準SQL函數而不是特定供應商的函數以提高可移植性。 -* 保證代碼簡潔明了並消除多余的SQL——比如非必要的引號或括號,或者可以推導出的多余`WHERE`語句。 -* 必要時在SQL代碼中加入註釋。優先使用C語言式的以`/*`開始以`*/`結束的塊註釋,或使用以`--`開始的行註釋。 +* 靈活使用空格和縮排來增強可讀性。 +* 儲存符合[ISO-8601][iso-8601]標準的日期格式(`YYYY-MM-DD HH:MM:SS.SSSSS`)。 +* 最好使用標準SQL函式而不是特定供應商的函式以提高可移植性。 +* 保證代碼簡潔明了並消除多餘的SQL——比如非必要的引號或括號,或者可以推導出的多餘`WHERE`語句。 +* 必要時在SQL代碼中加入註解。優先使用C語言式的以`/*`開始以`*/`結束的區塊註解,或使用以`--`開始的單行註解。 ```sql SELECT file_hash -- stored ssdeep hash @@ -40,9 +40,9 @@ UPDATE file_system * 駝峰命名法——它不適合快速掃描。 * 描述性的前綴或匈牙利命名法比如`sp_`或`tbl`。 -* 覆數形式——盡量使用更自然的集合術語。比如,用“staff”替代“employees”,或用“people”替代“individuals”。 +* 複數形式——盡量使用更自然的集合術語。比如,用“staff”替代“employees”,或用“people”替代“individuals”。 * 需要引用號的標識符——如果你必須使用這樣的標識符,最好堅持用SQL92的雙引號來提高可移植性。 -* 面向對象編程的原則不該應用到結構化查詢語言或數據庫結構上。 +* 物件導向程式設計的原則不該應用到結構化查詢語言或資料庫結構上。 ## Naming conventions 命名慣例 @@ -50,10 +50,10 @@ UPDATE file_system * 保證名字獨一無二且不是[保留字][reserved-keywords]。 * 保證名字長度不超過30個字節。 -* 名字要以字母開頭,不能以下劃線結尾。 -* 只在名字中使用字母、數字和下劃線。 -* 不要再名字中出現連續下劃線——這樣很難辨認。 -* 在名字中需要空格的地方用下劃線代替。 +* 名字要以字母開頭,不能以下底線結尾。 +* 只在名字中使用字母、數字和下底線。 +* 不要再名字中出現連續下底線——這樣很難辨認。 +* 在名字中需要空格的地方用下底線代替。 * 盡量避免使用縮寫詞。使用時一定確定這個縮寫簡明易懂。 ```sql @@ -63,7 +63,7 @@ SELECT first_name ### Tables 表名 -* 用集群名稱,或在不那麽理想的情況下,覆數形式。如`staff`和`employees`。 +* 用集合名詞,或在不那麽理想的情況下,複數形式。如`staff`和`employees`。 * 不要使用類似`tbl`或其他的描述性的前綴或匈牙利命名法。 * 表不應該同它的列同名,反之亦然。 * 盡量避免連接兩個表的名字作為關系表(relationship table)的名字。與其使用`cars_mechanics`做表名不如使用`services`。 @@ -122,7 +122,7 @@ SELECT SUM(s.monitor_tally) AS monitor_total 最好使用保留字的全稱而不是簡寫,用`ABSOLUTE`而不用`ABS`。 -當標準ANSI SQL關鍵字能完成相同的事情時,不要使用數據庫服務器相關的關鍵字,這樣能增強可移植性。 +當標準ANSI SQL關鍵字能完成相同的事情時,不要使用資料庫伺服器相依的關鍵字,這樣能增強可移植性。 ```sql SELECT model_num @@ -130,9 +130,9 @@ SELECT model_num WHERE p.release_date > '2014-09-30'; ``` -### White space 空白字符 +### White space 空白字元 -正確地使用空白字符對清晰的代碼十分重要。不要把代碼堆再一起或移除自然語言中的空格。 +正確地使用空白字元對清晰的代碼十分重要。不要把代碼堆在一起或移除自然語言中的空格。 #### Spaces 空格 @@ -158,9 +158,9 @@ SELECT model_num GROUP BY b.species_name, b.observation_date) ``` -註意`WHERE`和`FROM`等關鍵字,都右對齊,而真實的列名都左對齊。 +注意`WHERE`和`FROM`等關鍵字,都右對齊,而真實的列名都左對齊。 -註意下列情況總是加入空格: +注意下列情況總是加入空格: * 在等號前後(`=`) * 在逗號後(`,`) @@ -206,7 +206,7 @@ SELECT a.title, OR a.title = 'The New Danger'; ``` -### Identation 縮進 +### Identation 縮排 為確保SQL的可讀性,一定要遵守下列規則。 @@ -249,8 +249,8 @@ SELECT r.last_name, * 盡量使用`BETWEEN`而不是多個`AND`語句。 * 同樣地,使用`IN()`而不是多個`OR`語句。 -* 當數據輸出數據庫時需要處理時,使用`CASE`表達式。`CASE`語句能嵌套形成更覆雜的邏輯結構。 -* 盡量避免`UNION`語句和臨時表。如果數據庫架構能夠不靠這些語句運行,那麽多數情況下它就不應該依靠這些語句。 +* 當數據輸出資料庫時需要處理時,使用`CASE`表達式。`CASE`語句能嵌套形成更覆雜的邏輯結構。 +* 盡量避免`UNION`語句和臨時表。如果資料庫架構能夠不靠這些語句運行,那麽多數情況下它就不應該依靠這些語句。 ```sql @@ -268,21 +268,21 @@ SELECT CASE postcode 聲明模式信息時維護可讀代碼也很重要。所以列定義的順序和分組一定要有意義。 -在`CREATE`定義中,每列要縮進4個空格。 +在`CREATE`定義中,每列要縮排4個空格。 ### Choosing data types 選擇數據類型 -* 盡量不使用供應商相關的數據類型——這些類型可不能能在老系統上使用。 +* 盡可能避免使用供應商特定的數據類型。 它們不僅不可移植,而且可能不適用於相同供應商軟體的舊版本。 * 只在真的需要浮點數運算的時候才使用`REAL`和`FLOAT`類型,否則使用`NUMERIC`和`DECIMAL`類型。浮點數舍入誤差是個麻煩。 -### Specifying default values 指定默認類型 +### Specifying default values 指定預設類型 -* 默認值一定與列的類型相同——如果一個列的類型是`DECIMAL`那麽就不要使用`INTEGER`類型作為默認值。 -* 默認值要緊跟類型聲明並在`NOT NULL`聲明前。 +* 預設值一定與列的類型相同——如果一個列的類型是`DECIMAL`那麽就不要使用`INTEGER`類型作為預設值。 +* 預設值要緊跟類型聲明並在`NOT NULL`聲明前。 ### Constraints and keys 約束和鍵 -約束和鍵是構成數據庫系統的重要組成部分。它們能很快地變得難以閱讀和理解,所以遵從指導方針是很重要的。 +約束和鍵是構成資料庫系統的重要組成部分。它們能很快地變得難以閱讀和理解,所以遵從指南方針是很重要的。 #### Choosing keys 選擇鍵 @@ -290,10 +290,10 @@ SELECT CASE postcode 1. 鍵在某種程度上應該是獨一無二的。 2. 該值在不同表中的類型應該相同並且盡量不會更改。 -3. 該值是否會無法通過某種標準格式(如ISO發布的標準)?如 -4. 盡量讓鍵保持簡單,但在適當情況下不要害怕使用覆合鍵。 +3. 該值是否會無法通過某些標準格式(如ISO發布的標準)? 遵守第2點。 +4. 盡量讓鍵保持簡單,但在適當情況下不要害怕使用複合鍵。 -以上是定義數據庫時合乎邏輯的平衡做法。當需求變更時,鍵也應該根據情況更新。 +以上是定義資料庫時合乎邏輯的平衡做法。當需求變更時,鍵也應該根據情況更新。 #### Defining constraints 定義約束 @@ -311,12 +311,12 @@ SELECT CASE postcode * 如果該約束與多個列相關,那麽讓它盡量離與其相關的列距離越近越好。實在不行就講它放在表定義的最後。 * 如果是與整個表相關聯表級別的約束,那麽就將放在表的定義的最後。 * 按照字母順序安排定義,`ON DELETE`排在`ON UPDATE`前。 -* 有道理的話,把所有相關的語句對齊。比如,把所有`NOT NULL`定義對齊到同一列。雖然這樣的做法有些慢,但是能提高可讀性。 +* 必要的話,把所有相關的語句對齊。比如,把所有`NOT NULL`定義對齊到同一列。雖然這樣的做法有些慢,但是能提高可讀性。 ##### Validation 校驗 -* 用`LIKE`和`SIMILAR TO`約束來保證格式已知字符串的數據完整性。 -* 當數字的值的範圍可以確定時,用`CHECK()`來防止錯誤的值進入數據庫或被錯誤地轉換。大部分情況下至少要確認值要大於零。 +* 用`LIKE`和`SIMILAR TO`約束來保證格式已知字串的數據完整性。 +* 當數字的值的範圍可以確定時,用`CHECK()`來防止錯誤的值進入資料庫或被錯誤地轉換。大部分情況下至少要確認值要大於零。 * `CHECK()`約束應該在單獨的語句中以便debug。 ##### Example @@ -334,8 +334,8 @@ CREATE TABLE staff ( ### Design to avoid -* 面向對象設計思想並不適用於關系型數據庫——避免這個陷阱。 -* 將值存入一列並將單位存在另一列。列的定義應該讓自己的單位不言自明以避免在應用內進行合並。使用`CHECK()`來保證數據庫中的數據是合法的。 +* 物件導向程式設計並不適用於關聯式資料庫——避免這個陷阱。 +* 將值存入一列並將單位存在另一列。列的定義應該讓自己的單位不言自明以避免在應用內進行合並。使用`CHECK()`來保證資料庫中的數據是合法的。 * [EAV (Entity Attribute Value)][eav]表——用特殊的產品來處理無模式數據。 * 因為某些原因(如為了歸檔、為了劃分跨國公司的區域)將能合並在一起的表分開。這樣的設計導致以後必須使用`UNION`操作而不能直接查詢一個表。