# 49.3\. 錯誤消息風格指導 這份風格向導的目的是希望能把所有PostgreSQL 生成的消息維護一個一致的，用戶友好的風格。 ## 49.3.1\. 何去何從 主信息應該簡短，基于事實，并且避免引用類似特定函數名等這樣的實現細節。 "簡短"意味著"在正常情況下應該能放在一行里"。 如果需要保持主信息的簡短，或者如果你覺得需要提到失敗的特定系統調用之類的實現細節， 可以使用一個詳細信息。主信息和詳細信息都應該是基于事實的。 使用一個提示消息給出一個修補問題的提示，特別是在提出的建議可能并不總是有效的情況下。 比如，可以不這么寫： ``` IpcMemoryCreate: shmget(key=%d, size=%u, 0%o) failed: %m (plus a long addendum that is basically a hint) ``` 而是： ``` Primary: could not create shared memory segment: %m Detail: Failed syscall was shmget(key=%d, size=%u, 0%o). Hint: the addendum ``` 基本原理：保持主消息的簡短可以使它的內容有效， 并且讓客戶端的屏幕空間布局可以做出給錯誤信息保留一行就足夠的假設。 而詳細信息和提示信息可以轉移到一個冗余模式里，或者使一個彈出的錯誤細節的窗口。 同樣，詳細信息和提示信息通常都會在服務器日志里消除，以節約空間。 對實現細節的引用最好避免，因為畢竟用戶不知道細節。 ## 49.3.2\. 格式 不要在消息文本里放任何有關格式化的特定的假設。 除非是客戶端或者服務器日志為了符合自己需要回卷了長行。在長信息里， 新行字符(\n)可以用于分段建議。不要用新行結束一條消息。 不要使用 tab 或者其它格式化字符。在錯誤環境下的顯示里， 系統會自動給獨立級別的環境，比如，函數調用，增加新行。 基本原理：信息不一定非得在終端類型的顯示器上顯示。 在 GUI 顯示或者在瀏覽器里，這些格式指示器最好被忽略。 ## 49.3.3\. 引號 在需要的時候，英文文本應該使用雙引號引起來。其它語言的文本應該一致地使用一種引號， 這種用法應該和出版習慣以及其它程序的計算輸出一致。 基本原理：選擇雙引號而不是單引號從某種角度來說是隨機選擇，但是應該是最優的選擇。 有人建議過根據 SQL 傳統，在不同對象類型上使用不同的引號(也就是說， 字符串單引號，標識符雙引號)。但是這是一種語言內部的技巧，許多用戶甚至都不熟悉， 并且也不能厭戰到其它類型的引號場合，也不能翻譯成其它語言，而且也沒啥意義。 ## 49.3.4\. 使用引號 總是用引號分隔文件名，用戶提供的標識符，以及其它可能包含字的變量。 不要用引號包含那些不會包含字的變量(比如，操作符)。 在后端里有些函數會根據需要在他們的輸出上加雙引號 (比如 `format_type_be()`)。不要在這類函數的輸出上加額外的引號。 基本原理：對象的名字嵌入到信息里面之后，可能造成歧義。 在一個插入的名字的起始和終止的位置保持一致。 但是不要在信息里混雜大量不必要的或者重復的引號。 ## 49.3.5\. 語法和標點 對于主錯誤信息和詳細/提示信息，規則不同： 主錯誤信息：首字母不要大寫。不要用句號結束信息。絕對不要用嘆號結束一條信息。 詳細和提示信息：使用完整的句子，并且用句號終止每個語句。句子首字母大寫。 如有后面有另外一個句子，那么在句號后面放置兩個空格（對于英文來說； 可能不適合其他語言）。 錯誤上下文字符串：不要大寫首字母，不要用句號結束字符串。 上下文字符串應該通常不是完整的句子。 基本原理：避免標點可以讓客戶端應用比較容易的把信息嵌入到各種語言環境中。并且， 主消息也經常不是完整的句子。并且，如果信息長得超過一個句子， 那么就應該把他們分裂成主信息和詳細信息部分。不過， 詳細和提示信息長得多并且可能需要包含多個句子。為了保持一致， 這些句子應該遵循完整句子得風格，即使他們只有一個句子。 ## 49.3.6\. 大寫字符與小寫字符比較 消息用語使用小寫字符，包括主錯誤信息的首字母。 如果消息中出現 SQL 命令和關鍵字，用大寫。 基本原理：這樣很容易讓所有東西看起來都一樣，因為有些消息是完整的句子，有些不是。 ## 49.3.7\. 避免被動語氣 使用主動語氣。如果有主語，那么就使用完整的句子("A不能做 B")。 如果主語是程序自己，那么就使用電報風格的語言；不要用"我"作為程序的主語。 基本原理：程序不是人。不要假裝成其他的。 ## 49.3.8\. 現代時與過去時的比較 如果嘗試某事失敗，但可能下次嘗試的時候成功(可能是修補了某些問題之后)， 那么使用過去時。如果錯誤肯定是永久的，那么用現代時。 下面的兩個形式的句子之間有重要的語義差別： ``` could not open file "%s": %m ``` 和： ``` cannot open file "%s" ``` 第一個句子的意思是打開某個文件的企圖失敗。這個信息應該給出一個原因， 比如說"磁盤滿"或者"文件不存在"之類的。 過去時的語氣應該是合適的，因為下次磁盤可能不再是滿的，或者有問題的文件存在了。 第二種形式表示打開指定文件的功能根本就不在程序里存在，或者是這么做概念上是錯誤的。 現代時語氣是合適的，因為這個條件將無限期存在。 基本原理：當然，普通用戶將不會僅僅從信息的時態上得出大量的結論， 但是既然語言提供給語法，那么就應該正確使用。 ## 49.3.9\. 對象類型 在引用一個對象的名字的時候，說明它是什么類型的對象。 基本原理：否則，沒人知道"foo.bar.baz"指的是什么。 ## 49.3.10\. 方括弧 方括弧只用(1)在命令概要里表示可選的參數，或者(2)表示一個數組下標。 基本原理：任何其它的東西都不能對應這兩種眾所周知的習慣用法并且會讓人混淆。 ## 49.3.11\. 組裝錯誤信息 如果一個信息包含其它地方生成的文本，用下面的風格包含它： ``` could not open file %s: %m ``` 基本原理：很難估計所有可能放在這里的錯誤代碼并且把它放在一個平滑的句子里， 所以需要某種方式的標點。也曾經建議把嵌入的文本放在圓括弧里， 但是如果嵌入文本是信息的最重要部分，那么就不太自然，而這種情況是很經常的。 ## 49.3.12\. 錯誤的原因 消息應該總是說明為什么發生錯誤。比如： ``` BAD: could not open file %s BETTER: could not open file %s (I/O failure) ``` 如果不知道原因，那么你最好修補代碼。 ## 49.3.13\. 函數名 不要在錯誤信息里包含報告過程的名字。需要的時候，有別的機制找出這個函數，并且， 對于大多數用戶，這個信息也沒什么用。如果錯誤信息在缺少函數名的情況下沒有什么意義， 那么重新措辭。 ``` BAD: pg_atoi: error in "z": cannot parse "z" BETTER: invalid input syntax for integer: "z" ``` 也避免提及被調用的函數名字；應該說代碼試圖做什么： ``` BAD: open() failed: %m BETTER: could not open file %s: %m ``` 如果確實必要，在詳細信息里提出系統調用。在某些場合下， 提供給系統調用的具體數值是適合放在詳細信息里的。 基本原理：用戶不知道這些函數都干些啥。 ## 49.3.14\. 盡量避免的字眼 **Unable/不能.** "Unable/不能" 幾乎是被動語氣。最好使用 "cannot/無法"或者"could not"。 **Bad/壞的.** 類似"bad result/壞結果"這樣的錯誤信息真的是很難聰明地解釋。 最好寫出為什么結果是"bad/壞的"，比如，"invalid format/非法格式"。 **Illegal/非法.** "Illegal/非法"表示違反了法律，剩下的就是"invalid/無效的"。 但是最好還是說為什么無效。 **Unknown/未知.** 盡量避免使用"unknown/未知"。想想"error: unknown response"。 如果你不知道響應是什么，你怎么知道是錯誤?"Unrecognized/無法識別的" 通常是更好的選擇。還有最好要包括被抱怨的數值。 ``` BAD: unknown node type BETTER: unrecognized node type: 42 ``` **Find/找到 和 Exists/存在 比較.** 如果程序使用一個相當復雜的算法來定位一個資源(比如，一個路徑搜索)， 并且算法失敗了，那么說程序無法"find/找到"該資源是合理的。 但是，如果預期的資源位置是已知的但是程序無法在那里訪問它， 那么說這個資源不"exist/存在"。 這種情況下用"find/找到"聽起來語氣比較弱并且會混淆事實。 **May 和 Can 和 Might 比較.** "May"暗示權限（如，"You may borrow my rake."）， 在文檔或錯誤消息中很少使用。"Can"暗示能力 （如，"I can lift that log."），"might"暗示可能性 （如，"It might rain today."）使用適當的單詞澄清意義和幫助翻譯。 **縮寫.** 避免縮寫，像"can't"；使用"cannot"代替。 ## 49.3.15\. 正確地拼寫 用單詞的全拼。比如，避免下面這樣的縮寫： * spec * stats * parens * auth * xact 基本原理：這樣將改善一致性。 ## 49.3.16\. 本地化 請記住，錯誤信息文本是需要翻譯成其它語言的。遵循[Section 50.2.2](#calibre_link-2012) 里面的指導以避免給翻譯者造成太多麻煩。