swift博客 swift documentation

admin2024-08-22 8

Documentation/Comments

1 Documentation

如果某个函数不是简单地O(1)操作，那么最好就是为该函数添加一些注释文档，这样能有效地提高代码的可读性与可维护性。之前有个非常不错的文档工具VVDocumenter。推荐阅读Apple的官方指南中的描述：described in Apple’s Documentation.

Guidelines:

1.1 每行不应超过160个字符
1.2 即使某些注释只有一行，也应该使用块注释符： (/* /).
1.3 不用给每行的开头都加上： *.
1.4 使用新的 - parameter 标识符来代替老的:param: syntax (注意这边是小写的 parameter 而不是Parameter).
1.5 如果你准备对参数/返回值/异常值来写注释，那么注意要一个不落的全局加上，尽管有时候会让文档显得重复冗余。有时候，如果只需要对单个参数进行注释，那么还不如直接放在描述里进行声明，而不需要专门的为参数写一个注释。
1.6 对于复杂的使用类，应该添加一些具体的使用用例来描述类的用法。注意Swift的注释文档中是支持MarkDown语法的，这是一个很好的特性。

/**
 ## Feature Support
 This class does some awesome things. It supports:
 - Feature 1
 - Feature 2
 - Feature 3
 ## Examples
 Here is an example use case indented by four spaces because that indicates a
 code block:
     let myAwesomeThing = MyAwesomeClass()
     myAwesomeThing.makeMoney()
 ## Warnings:告警
 There are some things you should be careful of:
 1. Thing one
 2. Thing two
 3. Thing three
 */
class MyAwesomeClass {
    /* ... */
}

1.7 使用 - ` 在注释中著名引用的代码

/**
 This does something with a `UIViewController`, perchance.
 - warning: Make sure that `someValue` is `true` before running this function.
 */
func myFunction() {
    /* ... */
}

1.8 保证文档的注释尽可能的简洁

2 Other Commenting Guidelines:其他的注释规则

2.1 //后面总是要跟上一个空格
2.2 注释永远要放在单独的行中
2.3 在使用// MARK: - whatever的时候，注意MARK与代码之间保留一个空行

class Pirate {
    // MARK: - instance properties
    private let pirateName: String
    // MARK: - initialization
    init() {
        /* ... */
    }
}

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明原文出处。如若内容造成侵权/违法违规/事实不符，请联系SD编程学习网：675289112@qq.com进行投诉反馈，一经查实，立即删除！