• Swift 注释规范文档注释 2019-06-20 11:16:18
    Swift 注释规范 目录 Swift 注释规范 一、 普通注释 二、 MARK、TODO、FIXME 三、 文档注释 四、 Playground注释 今天,我知道我写是什么,上帝和我知道 明天,我知道这个代码什么意思, 后天,我知道这是...

    Swift 注释规范

    目录

    Swift 注释规范

    一、 普通注释

    二、 MARK、TODO、FIXME

    三、 文档注释

    四、 Playground注释


    今天,我知道我写是什么,上帝和我知道

    明天,我知道这个代码什么意思,

    后天,我知道这是我写的代码,

    一周后,这TM谁写的代码,此时只有上帝才知道啥意思

    论代码注释的重要性。

     

    一、 普通注释

    普通注释主要为了提示编码者,逻辑注释等作用,一般不会再文档中提示。

    1. 单行注释  //

    var str = ""
    // 修改str变量的值
    str = "a new value"
    
    

    2.多行注释 /*   */

    /*
    这里是多行注释
    多行注释里也可以成对出现
    /*
    子注释
    */
    
    */
    code

     

    二、 MARK、TODO、FIXME

     

    MARK:  代码文件结构标记,可以显示文件的大致结构和模块,说明建议使用首字母大写

    // MARK: - Properties
    // MARK: - Initialization
    // MARK: - IBAction Method
    // MARK: - XXXDelegate

    TODO: 待完成标记, 代表此处有需要完成的功能或者后续开发。

    // TODO: - 待完成的功能
    // TODO: - Need to finish

    FIXME:  检查标记, 通常用于需要检查的地方,比如临时修改变量为固定值方便测试,或者为了走通流程,注释部分代码等,都需要添加标记,方便后期提醒自己,万一忘了。最好上线前全局搜索检查下。

    代码文件结构(Ctr + 6 )

    代码文件结构

    三、 文档注释

    单行注释快捷键:⌘⌥/  【 CMD + Alt + / 】

    文档注释用于输出代码文档和阅读方便,规范的文档可以在Quick Help中看到或者Alt + 左键快速查看相关说明。更或者可以输出说明文档给别人使用

    文档注释也分为单行和多行,不过根据苹果Swift 开源代码可以看出 基本都使用单行注释

    文档注释的对象: 自定义类型、变量、方法等,但是重点还是方法说明

     

    Tip: 由于文档注释通常是多行和多标识字段, 所以此时就可以用Xcode Code Snippet 代码段收藏与引用

     

    单行注释 ///

    类型文档说明

    /// 用户信息
    struct UserInfo {
        /// 昵称
        var nickname: String
        /// 性别 ture: 男,  false: 女
        var isMale: Bool
    }

    可惜的是swift 没有发现对属性的行尾注释。

    方法文档说明

        /// 文档注释参考 【单行】
        /// - parameter pram: 单参数
        /// - returns : 返回结果是否成功 ture: 成功  false: 失败
        ///
        /// 其他discussion 详细说明  // 【注意】必须隔一行
        func singleLineComment(pram:String) -> Bool {
            print("注释参考")
            return true
        }

    多行注释 /**   */

        /**
         文档注释参考 【多行注释】  // 【注意:必须新起一行】
         - parameter p1: The number of Llamas spotted on the trip
         - parameter p2: The number of Llamas spotted on the trip
         - returns: 返回结果字符串数组
         
        其他discussion说明  // 【注意】同样必须隔一行
         */
        func text(p1:String , p2:Bool) -> [String] {
            return [String]()
            
        }

    支持 markdown 语法

    除了使用关键字比如ruturns 来让文档更好看之外,我们还可以使用markdown丰富说明。单行和多行文档注释都支持markdown,但是这个时候个人建议就使用多行注释

         /**
         # 支持markdown
         # 一级标题
         ## 二级标题也可以的
         注释参考2
         隔一行表示换行d
         
         三个”***"代表一条分割线
         ***
         ## 使用示例
         ```
         let result = testComment2(pram: "参数1", param2: true))
         ```
         
         ****
         - important:这个很重要
         - returns: 有返回值
         - parameter pram: The cubes available for allocation
         - parameter param2: The people that require cubes
        
         */
        func testComment2(pram:String, param2:Bool) -> Bool {
            print("markdown支持")
            return true
        }

    Quick Help 显示

    playground 示例代码: gitee

    swift Documentation

    四、 Playground注释

    苹果官方文档: Xcode Help -- Use playgrounds

    Playgound 也支持markdown , 而且还可以做成跳转文档的模式。

    比如,官网Sample Code, JSON与模型互转 下载即可

     

    展开全文
  • 苹果官方文档一般都很少去看,笔者参考官方文档和各路大神的经验,写下了一份基于Swift 4.0 的编码规范,并会持续更新,欢迎大家补充指正。 编码格式 命名规范 语法规范 1. 编码格式 1.1 使用二元...
  • Swift 文档注释规范 2016-01-23 20:40:48
    代码的结构和组织关乎了开发童鞋们的节操问题。明确和一致的代码表示了明确和一贯的思想。编译器并没有一个挑剔的口味,但当谈到命名,空格或文档,人类的差异就体现出来了。 NSHipster 的读者无疑会记得去年发表...
  • Swift 编码规范 2018-08-17 09:51:10
    一、swift简史 1、介绍 swift是苹果公司于2014年推出用于撰写OS和iOS应用程序的语言。它由苹果开发者工具部门总监“克里斯.拉特纳”在2010年开始着手设计,历时一年完成基本的架构。到后来苹果公司大力...
  • 1. 代码格式 1.1 使用四个空格进行缩进。 1.2 每行最多160个字符,这样可以避免一行过长。 (Xcode->Preferences->Text Editing->Page guide at column: 设置成160即可) ...1.4 确保每行都不以空白字符作为结尾 ...
  • Basic Operators 操作符是一种检查、操作、组合值的特殊的符号或短语。比如将两个值相加(let i = 1 + 2)的加号(+)。...Swift支持大多数标准C的操作符,而且为了消除错误增加了一些功能。赋值操作符(=)
  • iOS 官方 Swift API 设计规范 2018-10-15 10:00:29
    官方地址:API design guidelines 核心原则 最重要的目标:每个元素都能够准确清晰的表达出它的含义。做出 API 设计、声明后要检查在上下文中是否足够清晰明白。 清晰比简洁重要。虽然 swift 代码可以被写得很简短...
  • Xcode作为iOS的开发神器,为我们提供了十分丰富的文档提示功能,在开发过程中,我们可以十分方便的按下Option键,选中一个类或者方法查看其文档说明。而实际开发过程中我们也可以使用规范的方法添加注释,达到这样的...
  • iOS开发系列--Swift进阶 2018-08-07 22:45:34
    概述 上一篇文章《iOS开发系列--Swift语言》中对Swift的语法特点以及它和C、ObjC等其他语言的用法区别进行了介绍。当然,这只是Swift的入门基础,但是仅仅了解这些对于使用Swift进行
  • 官方文档的翻译,仅供参考,本人英语本就不好,边学边翻译,不喜勿喷。 Swift is a new programming language for iOS, OS X, watchOS, and tvOS apps that builds on the best of C and Objective-C, without the ...
  • swift代码规范 2019-09-24 16:58:20
    原文:https://github.com/raywenderlich/swift-style-guide#correctness 把重点的翻译了,有些生词已经...Updated for Swift 4.2 This style guide is different from others you may see, because the focus is ...
  • 全面的Swift学习资料整理 2016-12-30 17:08:14
    官方文档中文翻译http://wiki.jikexueyuan.com/project/swift/Github上的地址点我 Using Swift with Cocoa and Objective-C WWDC 2015  系统化的开发文档iOS Developer Library Swift 开源及跨平台开发swift.org ...
  • Swift学习资料@ SwiftGuide很赞 的Swift...Swift 30 Projects- 最新 Swift 3.0 的30个小App,更注重代码规范和架构设计(故胤道长) V2ex-Swift- 用 Swift 写的 V2EX 客户端。 iBBS-Swift- “新手开源一个用Swift...
  • 学习Swift也有一段时间了,但一直以来都是主打OC语言在开发项目。在这里也对Swift这门语言做个笔记。方便自己也方便大家。现在先不说Swift具体的知识语法。就先简单的说说 Swift 与 Objective-C 的混合编程吧,先做...
  • 命名(Naming) 使用驼峰式的描述性命名方式,为类,方法,变量等命名。类名的首字母应该大写,而方法和变量的首字母使用小写字符。 推荐做法: [cpp] view plaincopy ...private let maximumWidgetCount = 100...
  • 本教程手把手教您学习Xcode8和Swift3语言!一看就懂,一学就会! 视频教程拥有180节课程,包含iOS开发基础知识、数据处理、常用插件、信用卡卡号识别、自动化测试、网络访问、多线程、ShareSDK社会化分享、Core...
  • 17条 Swift 最佳实践规范 2015-11-25 15:29:28
    这是一篇 Swift 软件开发的最佳实践教程。 前言 这篇文章是我根据在 SwiftGraphics 工作时的一系列笔记整理出来的。文中大多数建议是经过深思熟虑的,但仍可以有其他类似的解决方法。因此,如果其他方案...
  • 使用Swift开发SDK的优点是,生成的SDK对于Obj-C或是Swift调用都不需要自己去建桥接文件,因为Swift的SDK打包时默认已经自动生成供OC调用的.h文件。OC调用时直接import,sdk中的.h文件即可。而Swift调用时,import该...
1 2 3 4 5 ... 20
收藏数 3,140
精华内容 1,256
热门标签