文档章节

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

法斗斗
 法斗斗
发布于 2016/03/03 10:43
字数 862
阅读 91
收藏 0
点赞 1
评论 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,如下图,这些地标注释会在下拉列表中粗体显示,点击列表项就会跳转到注释行。

© 著作权归作者所有

共有 人打赏支持
法斗斗
粉丝 20
博文 336
码字总数 6335
作品 0
杨浦
程序员
《从零开始学Swift》学习笔记(Day 57)—Swift编码规范:文件注释、代码注释、使用地标注

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

智捷课堂 ⋅ 2016/01/08 ⋅ 0

Java编码规范,在您进行编码之前应该阅读的规范

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

陈彦志 ⋅ 2011/09/19 ⋅ 0

PEP 8-Python编码规范整理

学习.png 我是用Python的IDE:pycharm来编写Python代码的,用IDE编写代码有一个好处就是语法高亮,智能提示。Python的代码样式规范称之为PEP 8规范,每次编写代码如果有出现不符合PEP 8规范的...

爱吃西瓜的番茄酱 ⋅ 2017/11/10 ⋅ 0

修改Xcode自动生成的文件注释来导出API文档

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

法斗斗 ⋅ 2016/05/30 ⋅ 0

java 注释规范

在软件开发的过程中总是强调注释的规范,但是没有一个具体的标准进行说明,通常都是在代码编写规范中简单的描述几句,不能作为一个代码注释检查的标准和依据,做什么都要有一个依据吗:),现在...

陈冠东 ⋅ 2013/01/05 ⋅ 0

Web前端团队开发规范文档

为新项目写的一份规范文档, 分享给大家. 我想前端开发过程中, 无论是团队开发, 还是单兵做站, 有一份开发文档做规范, 对开发工作都是很有益的. 本文档由本人编写, 部分意见来源于网络, 以此感...

乐派电影 ⋅ 2014/04/11 ⋅ 0

php编码规范

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

东子 ⋅ 2016/10/10 ⋅ 3

使用Beego+Swagger构建更好的API服务

一. 更好的API服务 在你已经在工作中写了很多版本,很多规范的API服务之后,你会发现,后端服务很多共性的工作需要去完成,比如: 1)良好的API说明文档,最好还附带可访问,试一试的服务url...

skywalker ⋅ 2017/08/02 ⋅ 0

标准的Java编码规范手册

编码规范体现出一个开发者的基本素质,良好的编码规范可以提高团队编码的效率,避免很多不必要的问题。今天分享一个标准的Java编码规范给大家,希望对于大家今后的开发工作带来帮助。 编码规...

mynameishuangshuai ⋅ 2016/05/10 ⋅ 0

Java开发过程中的编码规范总结

在日常实际开发中我们需要注意以下方面的编码规范: 《1》注释规范: 注释增加代码可读性,便于自己查找问题,也有利于其他工程师阅读你的代码,方便项目的后期维护。一般来说所有的类都要有...

小飞侠就是我 ⋅ 2016/03/17 ⋅ 2

没有更多内容

加载失败,请刷新页面

加载更多

下一页

JavaScript零基础入门——(八)JavaScript的数组

JavaScript零基础入门——(八)JavaScript的数组 欢迎大家回到我们的JavaScript零基础入门,上一节课我们讲了有关JavaScript正则表达式的相关知识点,便于大家更好的对字符串进行处理。这一...

JandenMa ⋅ 今天 ⋅ 0

sbt网络问题解决方案

转自:http://dblab.xmu.edu.cn/blog/maven-network-problem/ cd ~/.sbt/launchers/0.13.9unzip -q ./sbt-launch.jar 修改 vi sbt/sbt.boot.properties 增加一个oschina库地址: [reposit......

狐狸老侠 ⋅ 今天 ⋅ 0

大数据,必须掌握的10项顶级安全技术

我们看到越来越多的数据泄漏事故、勒索软件和其他类型的网络攻击,这使得安全成为一个热门话题。 去年,企业IT面临的威胁仍然处于非常高的水平,每天都会看到媒体报道大量数据泄漏事故和攻击...

p柯西 ⋅ 今天 ⋅ 0

Linux下安装配置Hadoop2.7.6

前提 安装jdk 下载 wget http://mirrors.hust.edu.cn/apache/hadoop/common/hadoop-2.7.6/hadoop-2.7.6.tar.gz 解压 配置 vim /etc/profile # 配置java环境变量 export JAVA_HOME=/opt/jdk1......

晨猫 ⋅ 今天 ⋅ 0

crontab工具介绍

crontab crontab 是一个用于设置周期性被执行的任务工具。 周期性执行的任务列表称为Cron Table crontab(选项)(参数) -e:编辑该用户的计时器设置; -l:列出该用户的计时器设置; -r:删除该...

Linux学习笔记 ⋅ 今天 ⋅ 0

深入Java多线程——Java内存模型深入(2)

5. final域的内存语义 5.1 final域的重排序规则 1.对于final域,编译器和处理器要遵守两个重排序规则: (1)在构造函数内对一个final域的写入,与随后把这个被构造对象的引用赋值给一个引用...

江左煤郎 ⋅ 今天 ⋅ 0

面试-正向代理和反向代理

面试-正向代理和反向代理 Nginx 是一个高性能的反向代理服务器,但同时也支持正向代理方式的配置。

秋日芒草 ⋅ 今天 ⋅ 0

Spring 依赖注入(DI)

1、Setter方法注入: 通过设置方法注入依赖。这种方法既简单又常用。 类中定义set()方法: public class HelloWorldOutput{ HelloWorld helloWorld; public void setHelloWorld...

霍淇滨 ⋅ 昨天 ⋅ 0

马氏距离与欧氏距离

马氏距离 马氏距离也可以定义为两个服从同一分布并且其协方差矩阵为Σ的随机变量之间的差异程度。 如果协方差矩阵为单位矩阵,那么马氏距离就简化为欧氏距离,如果协方差矩阵为对角阵,则其也...

漫步当下 ⋅ 昨天 ⋅ 0

聊聊spring cloud的RequestRateLimiterGatewayFilter

序 本文主要研究一下spring cloud的RequestRateLimiterGatewayFilter GatewayAutoConfiguration @Configuration@ConditionalOnProperty(name = "spring.cloud.gateway.enabled", matchIfMi......

go4it ⋅ 昨天 ⋅ 0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

返回顶部
顶部