作者：Erica Sadun，原文鏈接，原文日期：2016-1-28
譯者：ahfepj；校對：numbbbbb；定稿：Cee
郵件列表中對 SE-0023 API 設計指南（SE-0023 API Design Guidelines） 有大量討論。你可以在 swift.org 上找到原始的指南，我強烈推薦你閱讀一下。這個指南的大部分內容我都很喜歡，不過我認為有些命名和標簽規定過于嚴格。
文檔分為四章：基本原則、命名、慣例和特例。我完全同意基本原則這一章內容：要明確、清晰和簡潔，注釋一切。我已經寫了 Swift 文檔標記（Swift Documentation Markup）一書，這本書尊崇這些原則，另外還告訴你該如何實踐。同樣的原則適用于第四章：特例。
第二章重點介紹命名。第一節「提升使用的明確性」是這樣說的：增加適量的詞來避免歧義，去掉無用的詞，給弱類型參數添加角色名詞。對于這章我沒有任何問題，我對這些原則深有體會。第三節「使用術語」也沒什么問題。
然而，介紹命名的第二節不怎么樣。我之前批判過這節內容，雖然它「合乎語法」。我認為蘋果最好的做法是完全拋棄它，針對于這一部分，我已經寫了很長、很詳盡的反饋，但事情的發展已經不受我的控制。
問題出現在事物的命名上：用名詞來命名一個東西，用動詞來命名一個動作，這樣做合適嗎？說實話，在現有的指南中這或許是最好的辦法，可以避免一些。
或許你應該思考方法是否改變了實例，或許你應該將所有的副作用考慮進來，將他們和純函數區分開來。但是我們還沒討論「屬性-vs-方法」這種命名形式（更不用說命名本身可能導致的復雜性）。
我真心認為蘋果應該丟掉這一章，就像丟掉燙手的山芋那樣，而不是強迫大家按照它來工作，否則他們就會（像現在這樣）陷入麻煩。
我對慣例這一章也有一些看法，特別是關于參數標簽的問題。同樣，我在 GitHub 上寫了一些強有力的反饋，在反饋中我舉了一個例子，說明為什么邏輯相關參數應該比「省略第一個參數」的規則權重更高，同時說明了為什么一組互相關聯的函數調用應該用構造器式命名來強調它們的聯系。
關于這類問題，我寫了大量筆記，都快變成一本書了。不過，我確實計劃自出版一本書來介紹 Swift 范式。幾個月前我就已經開始了這項工作，只是碰巧看到了 SE-0023，現在我要繼續去寫書了。
下面是我寫的一些文章：
告別局部套用（看文章結尾重構后的風格）
更新 Linter（只是一些規則，不是 lint 工具）
和后綴遞減說再見（與 Swift 2.2 霸主 一文略有重疊）
等等。
本文由 SwiftGG 翻譯組翻譯，已經獲得作者翻譯授權，最新文章請訪問 http://swift.gg。
