《从零开始学Swift》学习笔记(Day 57)——Swift编码规范之注释规范:

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

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

前面说到Swift注释的语法有两种:单行注释(//)和多行注释(/*...*/)。这里来介绍一下他们的使用规范。

  1. 文件注释

文件注释就在每一个文件开头添加注释,文件注释通常包括如下信息:版权信息、文件名、所在模块、作者信息、历史版本信息、文件内容和作用等。

下面看一个文件注释的示例:

/*
Copyright (C) 2015 EorientInc. All Rights Reserved.
See LICENSE.txtfor this sample’s licensing information
 
Description:
This file contains thefoundational subclass of NSOperation.
 
History:
15/7/22: Created by TonyGuan.
15/8/20: Add socketlibrary
15/8/22: Add math library
*/

这个注释只是提供了版权信息、文件内容和历史版本信息等,文件注释要根据自己实际情况包括内容。

  1. 文档注释

文档注释就是这种注释内容能够生成API帮助文档。文档注释主要对类型、属性、方法或函数等功能。

文档注释是稍微将单行注释(//)和多行注释(/*...*/)做一点“手脚”后,就成为了文档注释,单行文档注释(///)和多行文档注释(/**...*/)。

下面代码示例:

import Foundation
 
/**
    The protocol that types may implement ifthey wish to be
       notified of significantoperation lifecycle events.
*/
protocol OperationObserver{
    
    /// Invoked immediately prior to the`Operation`‘s `execute()` method.
    func operationDidStart(operation:Operation)
  
}

代码中使用了文档注释。

可以使用一些工具将这些文档注释生成API文件

  1. 代码注释

程序代码中处理文档注释还需要在一些关键的地方添加代码注释,文档注释一般是给一些看不到源代码的人看的帮助文档,而代码注释是给阅读源代码人参考的。代码注释一般是采用单行注释(//)和多行注释(/*...*/)。

有的时候也会在代码的尾端进行注释,这要求注释内容极短,应该在有足够的空白来分开代码和注释。尾端注释示例代码如下:

init(timeout:NSTimeInterval) {
     self.timeout = timeout  //初始化
}
  1. 使用地标注释

随着编码过程深入,工程代码量会增加,任何在这大量的代码中能快速找到需要方法或者是刚才修改过代码呢?

在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

时间: 03-06

《从零开始学Swift》学习笔记(Day 57)——Swift编码规范之注释规范:的相关文章

Swift学习笔记

Apple 新推的Swift已经好几天了.对于向我这样的oc都还没完全琢磨透彻的菜鸟来说--(简直就是福利啊,joke) 看了几天的Swift,只是有了基本的印象.总感觉比较换混乱,可能源自与自己没怎么学过脚本语言.索性,边看边记,加深印象. 本来部分内容源自Apple的<The Swift Programming Language>以及互联网教程.其余内容均为个人理解,不保证正确. 进入正题: 1.Swift是什么? Apple唤他作:雨燕.其实英语过了四级的都应该看出来,Swift还有一层

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

原文:Swift学习笔记(一)搭配环境以及代码运行成功 1.Swift是啥? 百度去!度娘告诉你它是苹果最新推出的编程语言,比c,c++,objc要高效简单.能够开发ios,mac相关的app哦!是苹果以后大力推广的语言哦! 2.Swift给你带来什么机会? 当初你觉得objc太难,学ios学到一半放弃拉,或者进入it行业大家都搞android,你也搞android去了.现在你终于有机会和搞ios的站在一个语言的起跑线上,兄弟!swift传说很容易学哦,搞android的你想不想增加一下本领?提

SWIFT学习笔记05

1.Swift 无需写break,所以不会发生这种贯穿(fallthrough)的情况.2.//用不到变量名,可用"_"替换 for _ in 1...power { answer *= base } 3.case 可以匹配更多的类型模式,包括区间匹配(range matching),元组(tuple)和特定类型的描述. 可以这样用case case 1...3: naturalCount = "a few" 4.如果存在多个匹配,那么只会执行第一个被匹配到的 ca

SWIFT学习笔记02

1.//下面的这些浮点字面量都等于十进制的12.1875: let decimalDouble = 12.1875 let exponentDouble = 1.21875e1 let hexadecimalDouble = 0xC.3p0//==12+3*(1/16) 2.//类型别名,用typealias关键字来定义类型别名 typealias AudioSample = UInt16 var maxAmplitudeFound = AudioSample.min 3.//元组 let ht

swift学习笔记(三)关于拷贝和引用

在swift提供的基本数据类型中,包括Int ,Float,Double,String,Enumeration,Structure,Dictionary都属于值拷贝类型. 闭包和函数同属引用类型 捕获则为拷贝.捕获即定义这些常量和变量的原作用域已不存在,闭包仍然可以在闭包函数体内引用和修改这些值 class属于引用类型. Array的情况稍微复杂一些,下面主要对集合类型进行分析: 一.关于Dictionary:无论何时将一个字典实例赋给一个常量,或者传递给一个函数方法时,在赋值或调用发生时,都会

Swift学习笔记十二:下标脚本(subscript)

下标脚本就是对一个东西通过索引,快速取值的一种语法,例如数组的a[0].这就是一个下标脚本.通过索引0来快速取值.在Swift中,我们可以对类(Class).结构体(structure)和枚举(enumeration)中自己定义下标脚本的语法 一.常规定义 class Student{ var scores:Int[] = Array(count:5,repeatedValue:0) subscript(index:Int) -> Int{ get{ return scores[index];

Swift学习笔记四:数组和字典

最近一个月都在专心做unity3d的斗地主游戏,从早到晚,最后总算是搞出来了,其中的心酸只有自己知道.最近才有功夫闲下来,还是学习学习之前的老本行--asp.net,现在用.net做项目流行MVC,而不是之前的三层,既然技术在更新,只能不断学习,以适应新的技术潮流! 创建MVC工程 1.打开Visual studio2012,新建MVC4工程 2.选择工程属性,创建MVC工程 3.生成工程的目录 App_Start:启动文件的配置信息,包括很重要的RouteConfig路由注册信息 Conten

Swift学习笔记(二)参数类型

关于参数类型,在以前的编程过程中,很多时间都忽视了形参与实参的区别.通过这两天的学习,算是捡回了漏掉的知识. 在swift中,参数有形参和实参之分,形参即只能在函数内部调用的参数,默认是不能修改的,如果想要修改就需要在参数前添加var声明. 但这样的声明过后,仍旧不会改变实参的值,这样就要用到inout了,传递给inout的参数类型必须是var类型的,不能是let类型或者字面类型,(字面类型是在swift中常提的一个术语,个人认为就是赋值语句,也不能修改)而且在传递过程中,要用传值符号"&

Swift学习笔记十:属性

1.存储属性       1. 作为特定类或结构实例的一部分,存储属性存储着常量或者变量的值.存储属性可分为变量存储属性(关键字var描述)和常量存储属性(关键字let描述). struct student{ let name = "" var score = 0 } let a = student(name:"小笨狼",score:96)           注意:                ① 定义储存属性时,需要为每一个属性定义一个默认值.在初始化的时候,