文档章节

Swift编码规范之注释规范:文件注释、文档注释、代码注释、使用地标注释

法斗斗
 法斗斗
发布于 2016/03/03 10:43
字数 862
阅读 120
收藏 0
前面说到Swift注释的语法有两种:单行注释(//)和多行注释(/*...*/)。这里来介绍一下他们的使用规范。

1、文件注释就在每一个文件开头添加注释,文件注释通常包括如下信息:版权信息、文件名、所在模块、作者信息、历史版本信息、文件内容和作用等。
下面看一个文件注释的示例:
/*
Copyright (C) 2015 Eorient Inc. All Rights Reserved.
See LICENSE.txt for this sample’s licensing information
Description:
This file contains the foundational subclass of NSOperation.
History:
15/7/22: Created by Tony Guan.
15/8/20: Add socket library
15/8/22: Add math library
*/
这个注释只是提供了版权信息、文件内容和历史版本信息等,文件注释要根据自己实际情况包括内容。

2、文档注释
文档注释就是这种注释内容能够生成API帮助文档。文档注释主要对类型、属性、方法或函数等功能。
文档注释是稍微将单行注释(//)和多行注释(/*...*/)做一点“手脚”后,就成为了文档注释,单行文档注释(///)和多行文档注释(/**...*/)。
下面代码示例:
import Foundation
/**
    The protocol that types may implement if they wish to be
                         notified of significant operation lifecycle events.
*/
protocol OperationObserver {
    /// Invoked immediately prior to the `Operation`'s `execute()` method.
    func operationDidStart(operation: Operation)
}
代码中使用了文档注释。
可以使用一些工具将这些文档注释生成API文件

3、代码注释
程序代码中处理文档注释还需要在一些关键的地方添加代码注释,文档注释一般是给一些看不到源代码的人看的帮助文档,而代码注释是给阅读源代码人参考的。代码注释一般是采用单行注释(//)和多行注释(/*...*/)。
有的时候也会在代码的尾端进行注释,这要求注释内容极短,应该在有足够的空白来分开代码和注释。尾端注释示例代码如下:
init(timeout: NSTimeInterval) {
     self.timeout = timeout //初始化
}

4、使用地标注释
随着编码过程深入,工程代码量会增加,任何在这大量的代码中能快速找到需要方法或者是刚才修改过代码呢?
在Swift代码中使用地标注释,然后就可以使用Xcode工具在代码中快速查找了。地标注释有三个:
 MARK,用于方法或函数的注释。
 TODO,表示这里代码有没有完成,还要处理。
 FIXME,表示这里修改了代码。
这些注释会出现在Xcode的 Jump Bar中。来看一个示例:
class ViewController: UIViewController,
                        UITableViewDataSource, UITableViewDelegate {
    var listTeams: [String:String]!
    override func viewDidLoad() {
        super.viewDidLoad()
        ...
    }
    override func didReceiveMemoryWarning() {
        super.didReceiveMemoryWarning()
        //TODO: 释放资源 //使用TODO注释
    }
    // MARK: UITableViewDataSource 协议方法 //使用MARK注释
    func tableView(tableView: UITableView,
                                numberOfRowsInSection section: Int) -> Int {
        return self.listTeams.count
    }
    func tableView(tableView: UITableView,
                                cellForRowAtIndexPath indexPath: NSIndexPath) -> UITableViewCell {
        let cellIdentifier = "CellIdentifier"
        let cell: UITableViewCell! = tableView
                                        .dequeueReusableCellWithIdentifier(cellIdentifier,
                                                        forIndexPath: indexPath) as? UITableViewCell
        // FIXME: 修改bug //使用了FIXME注释
        let row = indexPath.row
        let rowDict = self.listTeams[row] as [String:String]
        ...
        return cell
    }
    // MARK: UITableViewDelegate 协议方法 //使用MARK注释
    func tableView(tableView: UITableView,
                                        didSelectRowAtIndexPath indexPath: NSIndexPath) {
        ...
    }
}
上述代码中使用三种地标注释,在使用时候后面要跟有一个冒号(:)。
注释之后如果使用呢?打开Xcode的 Jump Bar,如下图,这些地标注释会在下拉列表中粗体显示,点击列表项就会跳转到注释行。

本文转载自:

共有 人打赏支持
上一篇: swift命名规范
下一篇: swift 可选类型
法斗斗
粉丝 21
博文 367
码字总数 17774
作品 0
杨浦
程序员
私信 提问
《从零开始学Swift》学习笔记(Day 57)—Swift编码规范:文件注释、代码注释、使用地标注

原创文章,欢迎转载。转载请注明:关东升的博客 前面说到Swift注释的语法有两种:单行注释(//)和多行注释(/.../)。这里来介绍一下他们的使用规范。 1、文件注释 文件注释就在每一个文件开...

智捷课堂
2016/01/08
21
0
《Python从小白到大牛》第5章 Python编码规范

俗话说:“没有规矩不成方圆”。编程工作往往都是一个团队协同进行,因而一致的编码规范非常有必要,这样写成的代码便于团队中的其他人员阅读,也便于编写者自己以后阅读。 提示 关于本书的P...

tony关东升
07/04
0
0
Java编码规范,在您进行编码之前应该阅读的规范

本文转载于:http://www.web3d.com.cn/new/teach/java3d/2006/11/13/363276161.html Java编码规范 说明 1.1 为什么要有编码规范 编码规范对于程序员而言尤为重要,有以下几个原因: 一个软件...

陈彦志
2011/09/19
0
0
修改Xcode自动生成的文件注释来导出API文档

修改Xcode自动生成的文件注释来导出API文档 最近工作需要和其他公司进行项目交接的时候,原以为像往常一样直接交付源代码就行了,谁知道客户公司需要我们提供API文档。瞬间我和小伙伴们都惊呆...

法斗斗
2016/05/30
51
0
php编码规范

编码规范目录 1. 注释规范 2 2. 代码规范 3 3. 数据库规范 3 4. 接口规范 3 5. 文件规范 3 6. 性能规范 4 1. 注释规范 a.大段注释采用/**/的方式,通常为文件或函数的顶部,代码内部使用'//...

东子
2016/10/10
215
3

没有更多内容

加载失败,请刷新页面

加载更多

大数据教程(9.5)用MR实现sql中的jion逻辑

上一篇博客讲解了使用jar -jar的方式来运行提交MR程序,以及通过修改YarnRunner的源码来实现MR的windows开发环境提交到集群的方式。本篇博主将分享sql中常见的join操作。 一、需求 订单数据表...

em_aaron
20分钟前
1
0
十万个为什么之什么是resultful规范

起源 越来越多的人开始意识到,网站即软件,而且是一种新型的软件。这种"互联网软件"采用客户端/服务器模式,建立在分布式体系上,通过互联网通信,具有高延时(high latency)、高并发等特点...

尾生
26分钟前
1
0
《告诉你真实的美国教育》的读后感3900字

《告诉你真实的美国教育》的读后感3900字: 文章的开篇分析了我们耳熟能详的关于美国教育的小故事,就是那个因为幼儿园的老师教了“0”这个字母,然后妈妈告老师剥夺了孩子的想象力,再然后幼...

原创小博客
34分钟前
0
0
Terraform配置文件(Terraform configuration)

Terraform配置文件 翻译自Terraform Configuration Terraform用文本文件来描述设备、设置变量。这些文件被称为Terraform配置文件,以.tf结尾。这一部分将讲述Terraform配置文件的加载与格式。...

buddie
49分钟前
2
0
exportfs命令, vsftp搭建ftp服务

exportfs命令 当修改/etc/exports文件后,更改的内容是不会立即生效的。如果重启nfs服务,会导致客户端重启期间的请求是挂起等待的,可以把客户端的挂载umount进行卸载后,再重启nfs服务,但...

野雪球
今天
1
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部