原创文章,欢迎转载。转载请注明:关东升的博客

前面说到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工具在代码中快速查找了。地标注释有三个:

l   MARK,用于方法或函数的注释。

l   TODO,表示这里代码有没有完成,还要处理。

l   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,如下图,这些地标注释会在下拉列表中粗体显示,点击列表项就会跳转到注释行。

欢迎关注关东升新浪微博@tony_关东升。
关注智捷课堂微信公共平台,了解最新技术文章、图书、教程信息
  ​
更多精品iOS、Cocos、移动设计课程请关注智捷课堂官方网站:http://www.zhijieketang.com
智捷课堂论坛网站:http://51work6.com/forum.php

《从零开始学Swift》学习笔记(Day 57)——Swift编码规范之注释规范:文件注释、文档注释、代码注释、使用地标注释的更多相关文章

  1. Core Java 学习笔记——1.术语/环境配置/Eclipse汉化字体快捷键/API文档

    今天起开始学习Java,学习用书为Core Java.之前有过C的经验.准备把自己学习这一本书时的各种想法,不易理解的,重要的都记录下来.希望以后回顾起来能温故知新吧.也希望自己能够坚持把自己学习这本 ...

  2. 【swift学习笔记】四.swift使用Alamofire和swiftyJson

    Alamofire是AFNetworking的swift版本,功能灰常强大. github:https://github.com/Alamofire/Alamofire SwiftyJSON是操作js ...

  3. ES6 学习笔记(整理一遍阮一峰大神得入门文档,纯自己理解使用)

    1.let命令 1)let和var的区别:let声明的变量只有所在的代码块有效. 2)没有变量的提升,一定要声明后使用.使用let命令声明变量之前,该变量都是不可用的.形成“暂时性死区”. 3)typ ...

  4. Swift学习笔记(一)搭配环境以及代码运行成功

    原文:Swift学习笔记(一)搭配环境以及代码运行成功 1.Swift是啥? 百度去!度娘告诉你它是苹果最新推出的编程语言,比c,c++,objc要高效简单.能够开发ios,mac相关的app哦!是苹 ...

  5. 【swift学习笔记】二.页面转跳数据回传

    上一篇我们介绍了页面转跳:[swift学习笔记]一.页面转跳的条件判断和传值 这一篇说一下如何把数据回传回父页面,如下图所示,这个例子很简单,只是把传过去的数据加上了"回传"两个字 ...

  6. swift学习:第一个swift程序

    原文:swift学习:第一个swift程序 最近swift有点火,赶紧跟上学习.于是,个人第一个swift程序诞生了... 新建项目

  7. python之感知器-从零开始学深度学习

    感知器-从零开始学深度学习 未来将是人工智能和大数据的时代,是各行各业使用人工智能在云上处理大数据的时代,深度学习将是新时代的一大利器,在此我将从零开始记录深度学习的学习历程. 我希望在学习过程中做到 ...

  8. 从零开始学Java——个人笔记(持续更新中)

    从零开始学Java 学习流程 第一阶段:建立编程思想 Java概述 变量 运算符 控制结构 数组.排序和查找 面向对象编程(基础) 面向对象编程(中级) 项目&学习以致用 编程之乐 第二阶段: ...

  9. VSTO学习笔记(四)从SharePoint 2010中下载文件

    原文:VSTO学习笔记(四)从SharePoint 2010中下载文件 上一次我们开发了一个简单的64位COM加载项,虽然功能很简单,但是包括了开发一个64位COM加载项的大部分过程.本次我们来给CO ...

  10. [Swift通天遁地]七、数据与安全-(2)对XML和HTML文档的快速解析

    ★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★★➤微信公众号:山青咏芝(shanqingyongzhi)➤博客园地址:山青咏芝(https://www.cnblogs. ...

随机推荐

  1. 转载:Linux下执行SVN命令时提示错误:Valid UTF-8 data

    在Linux下执行svn add *时出现如下错误: svn:  Valid UTF-8  data(hex: 4b)followed by invalid UTF-8 sequence(hex:  ...

  2. 计算机原理--cpu篇

    简介 本文的目的是为了能够对特定的计算模型估算所需的CPU规格,个数. 这里主要介绍CPU的基本工作原理,指令集.(仅以X86体系结构的CPU为例 )

  3. 探寻BTree 索引对sql 优化影响

    从一道题開始分析: 如果某个表有一个联合索引(c1,c2,c3,c4)一下--仅仅能使用该联合索引的c1,c2,c3部分 A where c1=x and c2=x and c4>x and c ...

  4. 算法----堆排序(heap sort)

    堆排序是利用堆进行排序的高效算法,其能实现O(NlogN)的排序时间复杂度,详细算法分析能够点击堆排序算法时间复杂度分析. 算法实现: 调整堆: void sort::sink(int* a, con ...

  5. instanceof 与typeof的用法

    通常来讲,使用 instanceof 就是判断一个实例是否属于某种类型.例如: var oStringObject = new String("hello world"); con ...

  6. 【Android界面实现】View Animation 使用介绍

        转载请注明出处:http://blog.csdn.net/zhaokaiqiang1992     我们能够使用view animation 动画系统来给View控件加入tween动画(下称& ...

  7. 压力测试工具siege

    最近整改了一个线上服务,功能自测完毕后,需要进行性能的压力测试,同事推荐了siege这个工具,先熟悉一下相关的东西,后面有时间再好好研究它的源码实现.本文仅仅简单介绍一下这个工具的使用方法. 1.下载 ...

  8. matplotlib之创建极坐标系

    #!/usr/bin/env python3 #-*- coding:utf-8 -*- ############################ #File Name: polar.py #Auth ...

  9. C++类成员指针(指向类成员的指针)

    1.指向类的数据成员的指针: 声明格式如下: <类型说明符> <类名>::* <指针变量名>; 2.指向类的成员函数的指针: 声明格式如下:   <类型说明符 ...

  10. CCNA2.0笔记_子网划分

    http://files.cnblogs.com/files/airoot/%E5%AD%90%E7%BD%91%E5%88%92%E5%88%86.zip 网络 默认子网掩码 A类 255.0.0. ...