《从零开始学Swift》学习笔记（Day 57）——Swift编码规范之注释规范：文件注释、文档注释、代码注释、使用地标注释

span > 

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

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

 

 

Swift学习笔记——页面跳转 创建一个single view app后，项目中有main.storyboard，里面是一个viewcontroller。 那么我们如何实现页面跳转 首先添加一个导航控制器Navigation Controller。点击右上的➕，然后选择控件拖到面板上即可
Swift学习笔记——新建项目 在xcode菜单中选择 new - project - single view app 点击next在弹出窗中填写项目名称 这里languge有可以选择object-c或swift作为项目语言。这里我们学习swift，所以选择swift。 如果language选择swift，下面的user interface可以选择swiftUI和storyboard。 SwiftUI是2019 年 WWDC 大会上，苹果在压轴环节向大众宣布了基于 Swift 语言构建的全新 UI 框架，与flutter类似，是用代码编写页面，支持快速预览。
关东升 国内著名iOS/Cocos技术作家，iOS技术顾问，Cocos最有价值专家（CVP），智捷课堂首席培训专家。担任51CTO社区iOS技术顾问。 著有多部移动开发畅销书。