`

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

阅读更多

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

 

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

<!--[if !supportLists]-->l   <!--[endif]-->MARK,用于方法或函数的注释。

<!--[if !supportLists]-->l   <!--[endif]-->TODO,表示这里代码有没有完成,还要处理。

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



 

 

 

 

  • 大小: 21.1 KB
  • 大小: 99.4 KB
分享到:
评论

相关推荐

    从零开始学swift

    从零开始学swift,图灵原创,关东升著。基于swift2.x。2016年3月版

    Swift学习笔记与资料集合

    "Swift编程入门与精通.pdf" 通常是市面上的第三方教材,旨在帮助读者从零开始直至熟练掌握Swift。这本书可能包含了基础到进阶的所有内容,包括如何构建实际应用、使用Swift进行iOS开发的流程、Swift UI设计、Xcode...

    Swift学习笔记含项目代码.zip

    Swift学习笔记含项目代码.zipSwift学习笔记含项目代码.zipSwift学习笔记含项目代码.zipSwift学习笔记含项目代码.zipSwift学习笔记含项目代码.zipSwift学习笔记含项目代码.zipSwift学习笔记含项目代码.zipSwift学习...

    从零学习SwiftUI.zip

    以下是从零开始学习SwiftUI的一些建议: 了解Swift语言基础:SwiftUI是用Swift语言编写的,因此了解Swift语言的基础知识是非常重要的。你可以从苹果官方文档、在线教程或书籍中学习Swift语言。 学习SwiftUI基本概念...

    swift-stringscsv文件解析转换

    首先,`swift-strings&lt;——&gt;csv文件解析转换`这个标题暗示我们将关注两个主要部分:字符串操作和CSV文件处理。Swift内置的`String`类型提供了丰富的功能,可以用于处理和解析字符串。例如,我们可以通过`split`函数...

    从0开始入门学习Swift

    下载 Xcode,开始编写 Swift 代码,实践是学习的最好方式。从简单的程序开始,逐步增加难度,熟悉 Swift 的语法和特点。此外,加入 Swift 社区也是学习的重要一步。参加 Swift 社区,了解其他开发者的经验和分享,...

    Swift学习代码.zip

    这个名为"Swift学习代码.zip"的压缩包文件显然包含了用于学习Swift编程的各种代码示例和资源。从提供的文件列表来看,我们可以期待一系列按照天数划分的学习材料,分别从Day 01到Day 04,这通常代表了一个逐步深入的...

    swift-LEENote一个Xcode注释小插件

    2. **文档注释**:支持自动生成Swift标准的三尖括号(/**...*/)注释结构,方便编写API文档或者类、方法的描述。 3. **Markdown支持**:LEENote支持Markdown语法,使得注释内容可以更加格式化,如加粗、斜体、列表...

    IOS开发-Swift-基础知识学习笔记

    本学习笔记将深入探讨Swift的基础知识,帮助初学者快速掌握这一强大的工具。 一、Swift简介 Swift是由Apple在2014年WWDC(全球开发者大会)上推出的,旨在提高开发效率和代码安全。它吸收了Objective-C的优点,同时...

    swift-SwiftLint——Swift代码风格检查及自动格式化工具

    它可以帮助开发者遵循一致的编码规范,提升代码质量和可读性。SwiftLint基于规则进行工作,这些规则涵盖了命名规范、代码复杂度、冗余代码等多个方面,确保团队间的代码风格统一,同时也减少了代码审查的工作量。 ...

    swift学习笔记

    这篇学习笔记主要涵盖了Swift的基础知识和关键特性,旨在帮助初学者理解并掌握这种现代、强大且易读的语言。 一、Swift语言基础 Swift的语法简洁明了,易于理解。它引入了类型推断,使得编写代码时可以减少冗余的...

    iOS开发 swift语言入门 学习资料

    从Apple官方的“Swift Playgrounds”应用到各种在线教程和书籍,如《Swift编程语言》(The Swift Programming Language)官方指南,都提供了详细的学习路径。通过这些资源,你可以逐步了解并掌握变量与常量、控制流...

    swift 学习资料

    Swift是一种由苹果公司开发的编程语言,主要用于iOS、macOS、watchOS和tvOS等苹果平台的...由于文档中有一部分OCR扫描识别错误或漏识别的情况,对于学习者来说,最好能够找到完整的、准确的Swift编程手册来辅助学习。

    Swift4.0.3官方原版文档The Swift Programming Language(Swift4.0.3)

    《Swift4.0.3官方原版文档The Swift Programming Language》是Apple公司为开发者提供的权威指南,详尽阐述了Swift编程语言的各个方面。Swift是一种现代、高性能的编程语言,专为编写iOS、iPadOS、macOS、watchOS和...

    swift编程语言程序基础学习笔记

    ### Swift编程语言程序基础学习笔记 Swift是一种现代且高效的编程语言,主要用于开发iOS、macOS、watchOS和tvOS的应用程序。本篇笔记将重点介绍Swift的基础知识点,涵盖代码注释、变量定义、数据类型、条件控制、...

    Swift编程入门教程.pdf

    Swift编程入门教程,从零开始,深入浅出的Swift语言学习指南; Swift编程入门教程,从零开始,深入浅出的Swift语言学习指南; Swift编程入门教程,从零开始,深入浅出的Swift语言学习指南; Swift编程入门教程,从零...

    我的Swift学习项目实战代码.zip

    《Swift学习项目实战...总的来说,“我的Swift学习项目实战代码.zip”提供了一个从零开始学习Swift的宝贵资源。通过这三个阶段的实战项目,你将能够逐步掌握Swift语言的核心特性,并具备独立开发iOS应用程序的能力。

    SwiftNote:Swift学习笔记

    SwiftNote 是一个关于Swift编程语言的学习笔记集合,旨在帮助开发者深入了解和掌握Apple的这款现代、高性能的编程语言。这份笔记可能包含了从基础语法到高级特性的全面讲解,以及作者在学习过程中的心得和实践案例。...

    Swift学习资料

    通过观看活动视频回顾,学习者可以从专家的角度了解Swift的核心特性和最佳实践。同时,还可以参考现场的demo项目,这些项目都是实际开发中的典型应用场景,有助于提升学习者的实践能力。 - 视频回顾地址:...

Global site tag (gtag.js) - Google Analytics