代碼要寫註釋了嗎？

{"type":"doc","content":[{"type":"heading","attrs":{"align":null,"level":3},"content":[{"type":"text","text":"如何看待程序員不寫註釋？","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"最近在知乎上看到了這個話題：怎樣看待程序員不寫註釋？ 看了下瀏覽量居然有 30+w 次，看來大家討論的挺熱鬧，我瀏覽了大部分的回答，發現大家的觀點可以歸納爲以下幾點：","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"numberedlist","attrs":{"start":1,"normalizeStart":1},"content":[{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":1,"align":null,"origin":null},"content":[{"type":"text","text":"不寫註釋就是害人害己，別人看不懂，過幾天連自己也看不懂","attrs":{}}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":2,"align":null,"origin":null},"content":[{"type":"text","text":"好的代碼就是最好的註釋，我的代碼可讀性很好，沒必要寫註釋","attrs":{}}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":3,"align":null,"origin":null},"content":[{"type":"text","text":"只要有完善的文檔，代碼本身就是註釋","attrs":{}}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":4,"align":null,"origin":null},"content":[{"type":"text","text":"自己寫代碼時：“我自己寫的代碼還要寫註釋？” 看別人的代碼時：“臥槽這人居然不寫註釋？”","attrs":{}}]}]}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"對於程序員羣體，有位知乎網友的總結非常到位：程序員最討厭的四件事：1. 寫註釋 2. 別人不寫註釋 3. 寫文檔 4. 別人不寫文檔，不得不說我們程序員羣體真是個可愛而又敢於自黑的羣體。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https://static001.geekbang.org/infoq/f5/f50f7d46bd1f2da364b82d1cea8bf5bf.jpeg","alt":null,"title":null,"style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"說實話，我第一次看到這個話題的時候，我愣了一下，心想誰會提出這麼沙雕的問題，在我看來寫代碼不寫註釋，那不就跟耍流氓一樣嚒！在我第一天開始寫代碼的時候，我的老師就告訴我註釋的重要性，就好比渴了要喝水，餓了要喫飯一樣，這是編碼的習慣。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https://static001.geekbang.org/infoq/54/54e42b249163ca490cd3c6b19507d5a2.jpeg","alt":null,"title":null,"style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"我們寫代碼不僅僅是隻給編譯器看，還要給自己身邊的同事看，假如有一天休假，你把工作交接給了你的同事社會王，你正喫着火鍋唱着歌呢，社會王因爲幫你解決 Bug 而又看不懂你的代碼，給你來個奪命連環 Call，你還有什麼心思度假。有人也會說：“我自己寫的代碼只要我自己看的懂就行”，可事實上不寫註釋，時間一久，等需要重新拾起來的時候你就會發現：“臥槽，這是啥？這爲啥報錯”。所以給代碼添加合格的註釋不僅能夠讓別人更快速的接手你的代碼，也能更快的讓拾起自己的代碼。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https://static001.geekbang.org/infoq/30/30fef2043fee8226dd0688e09ac651ed.jpeg","alt":null,"title":null,"style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"heading","attrs":{"align":null,"level":3},"content":[{"type":"text","text":"迷惑行爲","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"在正式的給大家講解如何寫出合格的註釋之前，先給大家看下各種腦洞大開的代碼註釋：","attrs":{}}]},{"type":"heading","attrs":{"align":null,"level":4},"content":[{"type":"text","text":"鬥圖型","attrs":{}}]},{"type":"image","attrs":{"src":"https://static001.geekbang.org/infoq/4f/4f8996ffdd0ef77e12c71d7c7eab2fef.jpeg","alt":null,"title":null,"style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https://static001.geekbang.org/infoq/4f/4f232b8cbf793a8f1010e5f8daabe00e.jpeg","alt":null,"title":null,"style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https://static001.geekbang.org/infoq/95/9517dd2460c1ba5b566a486bcab299f3.jpeg","alt":null,"title":null,"style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https://static001.geekbang.org/infoq/94/94e7bd5e6ebd1c0f9c7b531db12ad78e.jpeg","alt":null,"title":null,"style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"heading","attrs":{"align":null,"level":4},"content":[{"type":"text","text":"吐槽型","attrs":{}}]},{"type":"image","attrs":{"src":"https://static001.geekbang.org/infoq/87/87a1871ce69ac0d670fd6b7db11fc535.jpeg","alt":null,"title":null,"style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https://static001.geekbang.org/infoq/3e/3e68ffc2ddf716ddb85d8c4d54f7abdc.jpeg","alt":null,"title":null,"style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https://static001.geekbang.org/infoq/bb/bbefdbea998efb86250c4543f9bae71b.jpeg","alt":null,"title":null,"style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https://static001.geekbang.org/infoq/5b/5bf40f86cb59c39182b09b3b91ecd73a.jpeg","alt":null,"title":null,"style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"heading","attrs":{"align":null,"level":4},"content":[{"type":"text","text":"炫耀型","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"italic","attrs":{}}],"text":"這是學生時期的謝爾蓋·布林，後來 Google 的聯合創始人之一，這位小夥子當時“低調”地把自己的待遇需求寫在了註釋裏。翻譯成中文大概意思就是“錢多事少大辦公室，經常免費去好玩的地方旅行，好耶！","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https://static001.geekbang.org/infoq/9a/9aac9b76b87dc1ec445c94811ddf739f.jpeg","alt":null,"title":null,"style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong","attrs":{}}],"text":"雷軍 23 年前寫的代碼","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https://static001.geekbang.org/infoq/9f/9ffb607d8f0a82df283e46be9be569aa.jpeg","alt":null,"title":null,"style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"text"},"content":[{"type":"text","text":"/* * You may think you know what the following code does. * But you dont. Trust me. * Fiddle with it, and youll spend many a sleepless * night cursing the moment you thought youd be clever * enough to \"optimize\" the code below. * Now close this file and go play with something else. */\n","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"italic","attrs":{}}],"text":"中文：你可能相信你能看懂以下代碼，但是其實絕對不可能，相信我。一旦你調試了，你絕對會後悔裝聰明去嘗試優化這段代碼。最好的方式是關閉文件，去玩點兒你喜歡的東西吧","attrs":{}}]},{"type":"heading","attrs":{"align":null,"level":4},"content":[{"type":"text","text":"菜雞型","attrs":{}}]},{"type":"codeblock","attrs":{"lang":"text"},"content":[{"type":"text","text":"// I am not sure if we need this, but too scared to delete. ... ...\n","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"italic","attrs":{}}],"text":"中文：個人不確認是不是需要，但是實在不敢刪除","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"text"},"content":[{"type":"text","text":"// I am not responsible of this code. // They made me write it, against my will.\n","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"italic","attrs":{}}],"text":"中文：個人不負責這塊的質量，因爲他們逼迫我違心的寫了這段代碼","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"text"},"content":[{"type":"text","text":"//This code sucks, you know it and I know it. //Move on and call me an idiot later.\n","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"italic","attrs":{}}],"text":"中文：這段代碼的確很挫，我知道你也知道，先不要罵我蠢，請先接着往下看.","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"看到上面這些靈魂極其有趣的程序員們各種腦洞大開，整起了各種類型的花活，我就只想問你們一下，你們的經理是不是不 review 你們的代碼？","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https://static001.geekbang.org/infoq/aa/aa62c4eb8f81029eca87c2e8b42b2ff1.jpeg","alt":null,"title":null,"style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"heading","attrs":{"align":null,"level":3},"content":[{"type":"text","text":"如何優雅的爲程序寫註釋？","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"“好的代碼不需要註釋”不等於“沒有註釋就是好的代碼”，好的代碼不需要註釋的前提是後面閱讀你代碼的人水平不能比你差太多，要寫出那種新人都能看懂的代碼，實在是太難了。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https://static001.geekbang.org/infoq/d6/d6e0c68b355c820d321dde056a14dc55.jpeg","alt":null,"title":null,"style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"說到這裏想必大家也知道了註釋的重要性，註釋可以幫助開發者在沒有閱讀代碼的情況下快速瞭解該接口的功能和用法，如果註釋寫的好，你的代碼也就更受人歡迎。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"既然註釋有這麼多好處，那還不來學習一下一名合格的程序員該如何寫註釋。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"blockquote","content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"以下注釋遵循 C++ 和 Swift 規範, 註釋選自開源項目：Kingfisher 和 Alamofire","attrs":{}}]}],"attrs":{}},{"type":"heading","attrs":{"align":null,"level":4},"content":[{"type":"text","text":"利用好註釋模板","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"註釋模板爲註釋寫作提供了極大的便利，我們常用的開發工具如 VS Code，Xcode 都對註釋模板有很好的支持；例如 Xcode, 只要在需要註釋的代碼的上一行按下快捷鍵：","attrs":{}},{"type":"text","marks":[{"type":"strong","attrs":{}}],"text":"opt + cmd + /","attrs":{}},{"type":"text","text":" 就可以添加註釋模板。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong","attrs":{}}],"text":"示例如下：","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"image","attrs":{"src":"https://static001.geekbang.org/infoq/c0/c08e4e3b2e2f494da099dad96411e78a.jpeg","alt":null,"title":null,"style":[{"key":"width","value":"75%"},{"key":"bordertype","value":"none"}],"href":null,"fromPaste":true,"pastePass":true}},{"type":"heading","attrs":{"align":null,"level":4},"content":[{"type":"text","text":"註釋風格","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"// 或者 /// 或 /* */ 都可以; 但 // 更 常用， 要在如何註釋及註釋風格上確保統一。","attrs":{}}]},{"type":"heading","attrs":{"align":null,"level":4},"content":[{"type":"text","text":"文件註釋","attrs":{}}]},{"type":"blockquote","content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"文件註釋描述了該文件的內容，每個文件註釋都要包含以下內容：文件內容的簡要描述，作者信息，日期，版權信息聲明","attrs":{}}]}],"attrs":{}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"文件註釋的順序應該如下：","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"numberedlist","attrs":{"start":1,"normalizeStart":1},"content":[{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":1,"align":null,"origin":null},"content":[{"type":"text","text":"文件內容的簡要描述","attrs":{}}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":2,"align":null,"origin":null},"content":[{"type":"text","text":"作者信息","attrs":{}}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":3,"align":null,"origin":null},"content":[{"type":"text","text":"日期","attrs":{}}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":4,"align":null,"origin":null},"content":[{"type":"text","text":"版權信息聲明，例如：Copyright 2008 Google Inc。 必要的話還可以加上許可證樣板，例如：Apache 2.0, BSD, LGPL, GPL","attrs":{}}]}]}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong","attrs":{}}],"text":"示例如下：","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"swift"},"content":[{"type":"text","text":"//\n// Kingfisher.swift\n// Kingfisher\n//\n// Created by Wei Wang on 16/9/14.\n//\n// Copyright (c) 2019 Wei Wang \n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in\n// all copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\n// THE SOFTWARE.\n","attrs":{}}]},{"type":"heading","attrs":{"align":null,"level":4},"content":[{"type":"text","text":"類註釋","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"類註釋應該要爲讀者提供使用該類的足夠信息, 同時應當提醒讀者在使用此類時要注意的事項。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong","attrs":{}}],"text":"示例如下：","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"swift"},"content":[{"type":"text","text":"import Foundation\n\n/// `Session` creates and manages Alamofire's `Request` types during their lifetimes. It also provides common\n/// functionality for all `Request`s, including queuing, interception, trust management, redirect handling, and response\n/// cache handling.\nopen class Session {\n \n ...\n\n}\n","attrs":{}}]},{"type":"heading","attrs":{"align":null,"level":4},"content":[{"type":"text","text":"函數註釋","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"我們要在每個函數的聲明處前加上註釋, 描述該函數的功能和用途. 只有在函數的功能通俗易懂時纔可以省略這些註釋 (例如, 簡單的取值和設值函數).。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong","attrs":{}}],"text":"示例如下：","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"swift"},"content":[{"type":"text","text":"/// Creates a `DataRequest` from a `URLRequest` created using the passed components and a `RequestInterceptor`.\n ///\n /// - Parameters:\n /// - convertible: `URLConvertible` value to be used as the `URLRequest`'s `URL`.\n /// - method: `HTTPMethod` for the `URLRequest`. `.get` by default.\n /// - parameters: `Parameters` (a.k.a. `[String: Any]`) value to be encoded into the `URLRequest`. `nil` by\n /// default.\n /// - encoding: `ParameterEncoding` to be used to encode the `parameters` value into the `URLRequest`.\n /// `URLEncoding.default` by default.\n /// - headers: `HTTPHeaders` value to be added to the `URLRequest`. `nil` by default.\n /// - interceptor: `RequestInterceptor` value to be used by the returned `DataRequest`. `nil` by default.\n /// - requestModifier: `RequestModifier` which will be applied to the `URLRequest` created from the provided\n /// parameters. `nil` by default.\n ///\n /// - Returns: The created `DataRequest`.\n open func request(_ convertible: URLConvertible,\n method: HTTPMethod = .get,\n parameters: Parameters? = nil,\n encoding: ParameterEncoding = URLEncoding.default,\n headers: HTTPHeaders? = nil,\n interceptor: RequestInterceptor? = nil,\n requestModifier: RequestModifier? = nil) -> DataRequest {\n let convertible = RequestConvertible(url: convertible,\n method: method,\n parameters: parameters,\n encoding: encoding,\n headers: headers,\n requestModifier: requestModifier)\n\n return request(convertible, interceptor: interceptor)\n }\n","attrs":{}}]},{"type":"heading","attrs":{"align":null,"level":4},"content":[{"type":"text","text":"變量註釋","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"通常我們取變量名稱的時候已經將其意義說明了。但是在邏輯複雜的情況下, 還是需要添加一些註釋說明來做特別說明。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong","attrs":{}}],"text":"示例如下：","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"swift"},"content":[{"type":"text","text":"/// Underlying `URLSession` used to create `URLSessionTasks` for this instance, and for which this instance's\n /// `delegate` handles `URLSessionDelegate` callbacks.\n ///\n /// - Note: This instance should **NOT** be used to interact with the underlying `URLSessionTask`s. Doing so will\n /// break internal Alamofire logic that tracks those tasks.\n ///\n public let session: URLSession\n","attrs":{}}]},{"type":"heading","attrs":{"align":null,"level":4},"content":[{"type":"text","text":"TODO 註釋","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"對那些臨時的, 短期的解決方案, 使用 TODO 註釋。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong","attrs":{}}],"text":"示例如下：","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"c++"},"content":[{"type":"text","text":"// TODO([email protected]): Use a \"*\" here for concatenation operator.\n// TODO(Zeke) change this to use relations.\n// TODO(bug 12345): remove the \"Last visitors\" feature\n","attrs":{}}]},{"type":"heading","attrs":{"align":null,"level":4},"content":[{"type":"text","text":"棄用註釋","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"通過註釋（","attrs":{}},{"type":"text","marks":[{"type":"italic","attrs":{}},{"type":"strong","attrs":{}}],"text":"DEPRECATED","attrs":{}},{"type":"text","text":" comments）來標記接口已棄用，並要說明後續的替代方案。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong","attrs":{}}],"text":"示例如下：","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"swift"},"content":[{"type":"text","text":"/// Gets an image deserialized from provided data.\n ///\n /// - Parameters:\n /// - data: The data from which an image should be deserialized.\n /// - options: Options for deserialization.\n /// - Returns: An image deserialized or `nil` when no valid image\n /// could be deserialized.\n /// - Note:\n /// This method is deprecated. Please implement the version with\n /// `KingfisherParsedOptionsInfo` as parameter instead.\n @available(*, deprecated,\n message: \"Deprecated. Implement the method with same name but with `KingfisherParsedOptionsInfo` instead.\")\n func image(with data: Data, options: KingfisherOptionsInfo?) -> KFCrossPlatformImage?\n","attrs":{}}]},{"type":"heading","attrs":{"align":null,"level":3},"content":[{"type":"text","text":"最後","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"註釋雖然寫起來很痛苦, 但對保證代碼可讀性至關重要。 總而言之，學會寫好代碼註釋，是每一個程序員的必備技術，也是一種良好的編程習慣，不僅僅是爲了開發團隊中的小夥伴，也是爲了面對將來的自己。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong","attrs":{}}],"text":"參考資料：","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"numberedlist","attrs":{"start":1,"normalizeStart":1},"content":[{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":1,"align":null,"origin":null},"content":[{"type":"text","text":"https://zh-google-styleguide.readthedocs.io/en/latest/google-cpp-styleguide/comments/","attrs":{}}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":2,"align":null,"origin":null},"content":[{"type":"text","text":"https://bbs.huaweicloud.com/blogs/176194","attrs":{}}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":3,"align":null,"origin":null},"content":[{"type":"text","text":"https://github.com/onevcat/Kingfisher","attrs":{}}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":4,"align":null,"origin":null},"content":[{"type":"text","text":"https://github.com/Alamofire/Alamofire","attrs":{}}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":5,"align":null,"origin":null},"content":[{"type":"text","text":"https://www.zhihu.com/question/27246926/answer/1214585389","attrs":{}}]}]}]}]}