昨天，一位名叫安德魯·華納的開發者撰寫的這篇文章引起了一些爭論。文章標題「警惕注釋的『塞壬之歌』」（譯者注：塞壬是希臘神話中的海妖，她的歌聲極具迷惑性，會引起海嘯等災難）暗示了開發人員在自欺欺人，因為注釋會降低**的質量：
注釋在腐爛。它們不會被編譯，並且永遠不會在執行時被執行。如果注釋過時或者不正確，測試不會因此而失敗，也沒有使用者會抱怨。和注釋打交道的程式設計師擔心「有人可能需要這個注釋，或者該注釋會對將來的開發帶來幫助」，所以在注釋真正有用之前就在**中引入了很多注釋（甚至你還得先證明它們的確是有用的）。他的建議是什麼呢？
你沒有任何藉口能為寫注釋做辯解。給這些方法乙個加 try 語法，我保證你會有乙個更純淨、更易維護的**庫。我不主張用注釋來補救那些糟糕的程式設計，比如差勁的命名或者有缺陷的演算法。我相信注釋在良好的**實踐中會發揮重要的作用——無論你的**僅限內部使用還是作為公共 api。
正如幾周前我在這篇部落格上討論過的，正在寫**的你與「未來的你」、你的團隊以及你**的讀者之間存在著很大的差別。現在我不得不說一說「swift 風格」的注釋：
注釋、注釋、還是注釋！當你需要寫注釋的時候，別忘了寫測試。測試可以為你節省思考「我在這做什麼」花費的全部時間，因為你可以看到**出問題了並且驗證執行的結果是否符合預期。**寫的越少越好，然後把省下的時間用來更清晰地表述你所寫的**。遇到那些不夠明顯的、棘手的或者反直覺的邏輯，注釋可以向讀者解釋：這是故意為之。這個事件會影響那個事情；這部分資料在該階段並未驗證；這個過程由它的 delegate 負責。注釋可以使你明確你的假設被應用到**中的哪些部分，它還允許你評價**的質量。當然這有助於留下乙個「todo」：**的開銷在什麼地方（「這裡的效能真的很糟糕」），但是現在我們不得不使用它，對於當前剛好發生的錯誤留下一些觀點，還有那些在你腦中一閃而過的想法。你理解了過去的東西，但是對於未來總是無能為力的。
修復過去的東西的開銷總是很小的，因為你已經把它的完整設計裝在了自己腦中。重新設計並且恢復到正常的開發速度將付出巨大的代價。
注釋記錄了你的意圖。注釋中可能提到之前嘗試過的方法以及這些方法被放棄的原因。也可以討論設計的決策是如何提出的——曾經探索過哪些方案，以及為什麼其中的一些方案最終未被採納。
注釋使你讀懂**背後的思想。提交時的描述（commit messages）很有幫助，但是我不認為這些描述適合記錄解決方案或者意外的行為。如果**在另乙個專案中重用的話，附帶的版本控制歷史可能不會與源**同步。
注釋提供了乙個麵包屑跟蹤的設計，不儲存在工作記憶（working memory）中，僅僅依靠讀**或者掃瞄性質的測試並不能意會其中的含義。意料之外的複雜事物是你最想注釋的事情之一。事實上，意外事件的注釋非常重要，因為意外本質上就是乙個 bug。
注釋並不只針對不佳的設計和**。它們記錄了修正**的過程，支援在將來進行閱讀和修改。良好的注釋可以減少**的讀者閱讀**所花費的精力，便於他們集中注意力去理解特定的任務，比如「我如何去增加這個特性」，而不是「這裡發生了什麼」。雖然良好的**有時可以做到「自文件化」，但是這並不意味著它總是可以（或者經常可以）自文件化。
作為拜訪「過去的你」的墊腳石，好的注釋可以記錄你當時的想法以及解釋為什麼你會選擇這樣的做事方式。無論你期望你的**讀者是多麼的聰明或有洞察力，你過去的設計意圖都不應該成為他們的謎題或者負擔。
Swift文件注釋
a dome method param input an int number returns the string represents the input number func method input int string return string input 在文件注釋的塊中 在這裡是被...
Swift 文件注釋規範
的結構和組織關乎了開發童鞋們的節操問題。明確和一致的 表示了明確和一貫的思想。編譯器並沒有乙個挑剔的口味，但當談到命名，空格或文件，人類的差異就體現出來了。nshipster 的讀者無疑會記得去年發表的關於文件的文章，但很多東西已經在 xcode 6 中發生了變化 幸運的是，基本上算是變得更好了 因...
趙雅智 Swift（3） swift注釋
請將你的 中的非執行文字注釋成提示或者筆記以方便你將來閱讀。swift 的編譯器將會在編譯 時自動忽略掉注釋部分。以雙正斜槓作 為起始標記 這是乙個注釋 其起始標記為單個正斜槓後跟隨乙個星號 終止標記為乙個星號後跟隨單個正斜槓 這是乙個,多行注釋 swift 的多行注釋可以巢狀在其它的多行注釋之中。...