快速提示：文档

在编写漂亮的“自我文档”代码和添加自己的解释性注释之间，代码文档始终是拉锯战。 自我记录代码始终是目标，但有时简单的注释将有助于您节省时间和精神疲劳。

为了帮助您达到适当的平衡，我们收集了一些有用的文档提示，可在您的代码库中使用。

Xcode带有方便的功能，称为快速帮助。 这是在Option + Clicking代码库时看到的漂亮的文档弹出窗口。 该文档还显示在“实用工具”抽屉的“快速帮助”面板中。 快速帮助功能通过允许您记住实际操作的实际情况，可以真正地节省大量时间。

您还可以创建自己的快速帮助文档。 在类，结构，枚举，属性，方法等上方直接以/// …或/** … */形式的注释将呈现为快速帮助。 在此注释中，您可以使用类似于Markdown的语法来编写丰富的文档，其中包括基本的文本格式，示例代码，链接，甚至是图像和视频。 有关所有详细信息，请参见Apple的标记格式参考。

当光标位于函数上时，要记住的方便快捷方式是Command + Option + / 。 这将自动为您的函数生成一个可随时填写的模板，包括参数列表和返回类型。

专家提示：游乐场具有自己独特的文档功能，包括将特殊注释（ /*: … */和//: … ）呈现为精美的，类似于打印的格式的能力，非常适合为您的团队或团队构建培训材料甚至用作演示媒体。

有时候，您只需要一个简单的注释即可帮助您慢走记忆或指出代码中有些棘手的内容。 以下是一些有用的约定：

• // MARK:可用于概述代码。 这些与属性和方法声明一起显示在跳转栏中。 它们是Swift的#pragma mark -版本。
• // TODO:在标记将来的工作位置时非常有用，尤其是在布置完成当前任务所需的子任务时。 这些特殊注释显示在Xcode的跳转栏中，因此我想通过将内容包装在星号上来使其脱颖而出（例如// TODO: *** … *** ）。 评论应简短而切题。 如果需要提供更多信息，请将其放在下一行的另一条注释中。 您的代码库不应堆满未完成的TODO。 我们将在短期内讨论一种防止这种情况的方法。
• // FIXME:与TODO类似，除了它通常表示损坏的东西，而不是不完整的东西。 这些应该遵循与TODO类似的约定，包括不要长期坚持。
• // NOTE:当留下有关某项工作原理的信息或指出特殊注意事项时，遵循的有用约定。
• // IMPORTANT:有助于区分非常重要的音符。 您还可以提出自己的方案来标记重要信息。

专家提示：在您的有用评论上签名并注明日期（ // NOTE: … ~ ABC 2017–02–07 ），以便人们始终知道是谁撰写的。 在重构期间，通过简单的复制和粘贴就可以在源代码管理中丢掉责备。

这些特殊注释可以直接集成到您的构建系统中。 例如，如果所有// TODO:和// FIXME:注释都显示为Xcode警告，那不是很好吗？ 这是可能的，并且使用自定义构建阶段很容易完成。 诸如[swiftlint]（）之类的工具已预加载了此功能，但您也可以使用简单的脚本来滚动自己的工具。 这是来自Stack Overflow的示例脚本，该脚本在编译时将TODO和FIXME标记为警告：

 如果[“ $ {CONFIGURATION}” =“ Debug”]; 然后
   TAGS =““待办事项：| FIXME：”
  回声“在$ {SRCROOT}中搜索$ {TAGS}”
  找到“ $ {SRCROOT}” \（-name“ * .swift” \）-print0 |  xargs -0 egrep \
   — with-filename \
   - 电话号码 \
   —唯一匹配的“（$ TAGS）。* \ $” \
   |  perl -p -e“ s /（$ TAGS）/警告：\ $ 1 /”
科幻 

Swift仍在不断发展，但是养成用有用的文档编写清晰一致的代码的习惯，从长远来看将为您（和您的团队成员）提供良好的服务。 如果您有我们此处未涉及的Swift文档提示，请在下面的评论中向我们介绍它们，或在Twitter上与我们分享。

在我们深入了解有关组织您的项目的建议时，请务必在下周一再回来查看。

---

有关设计和开发的更多见解，请订阅 BPXL Craft 并在 Twitter上 关注Black Pixel 。

Black Pixel是一家创意数字产品代理商。 了解更多信息，请访问 blackpixel.com 。