关于Swift开发中的注释技巧

前言

代码注释对于一个开发者来说至关重要。可以很负责任的说，一个好的开发者一定要会写一手漂亮的代码注释。我曾经接手过一份一句代码注释都没有的项目，我记得当时每遇到一个Bug我都会问候一下写这份代码的前辈。所以好的代码注释技巧和好的代码注释工具是我们快速开发和维护的利剑。
我之前用的最好的代码注释插件是王巍写的VVDocumenter，这个插件应该是当年风靡iOS程序圈的一款利器，它干净、美观、易懂，不幸的是苹果在Xcode8.0之后屏蔽了所有第三方插件，让我一度觉得以后的工作都不能好好注释了。好在苹果在Xcode8.0之后增加了自己的代码注释体系，下面我就来总结一下Swift开发中那些注释技巧。

正文

学过Objective-C的人都知道，在Objective-C中的注释跟大多数语言的注释基本一致，然而苹果在开发Swift语言的时候了采用新的注释语句，更加人性化和通俗易懂。

• Objective-C中的代码注释
  • 文件注释
    1. 单行文件注释

    // 这里写注释内容 
    

    2. 多行文件注释

    /*
     这里写多行注释内容，这里的内容可以很多可以无限制换行，可以把项目的一些版权信息
     和一些说明性信息写在这种注释里面。
     */
    

  • 文档注释
    1. 单行文档注释

    /// 这里可以标注单行文档信息注释
    

    2. 多行文档注释

    /**
     * 通过姓名、年龄、性别创建一个视图并返回
     *
     * @param name   姓名
     * @param age    年龄
     * @param gender 性别
     * @return       创建好的视图
     */
    - (UIView)studentWithName:(NSString *)name age:(int)age gender:(BOOL)gender {
    
    }
    

  • 地标注释

    1. pragma

       #pragma mark - UITableViewDelegate
       

       pragma注释展示

    2. warning

    #warning 当出现内存警告的时候这里需要将内存占有率高的变量释放掉
    - (void)didReceiveMemoryWarning {
      [super didReceiveMemoryWarning];
      // Dispose of any resources that can be recreated.
    }
    

    warning警告展示
    

    这种警告提醒方式不得不说对于有强迫症的程序员来说实在是太不友好了，分分钟都想把它删掉，甚至有时候做项目的时候一天可能来来回来要看上它几百遍，本人极少会使用到这种方式注释代码。

• Swift中的代码注释

  • 文件注释

    1. 单行文件注释

    // 这里写注释内容
    

    2. 多行文件注释

    /*
      这里写多行注释内容，这里的内容可以很多可以无限制换行，可以把项目的一些版权信息
      和一些说明性信息写在这种注释里面。
     */
    

  • 文档注释

    1. 单行文档注释

    /// 这里写注释内容 
    

    2. 多行文档注释

    /// 通过姓名、年龄、性别创建一个视图并返回
    ///
    /// - Parameters:
    ///   - name:   姓名
    ///   - age:    年龄
    ///   - gender: 性别
    /// - Returns:  创建好的视图
    func student(name : String, age : Int, gender : Bool) -> UIView {
      
    }
    

  • 地标注释

    1. MARK:

    // MARK: UITableViewDelegate
    

    MARK地标注释展示Xcode9.0效果
    2. TUDO:

    //TODO:进入这个方法表示已接收到内存警告，需要做出处理
    override func didReceiveMemoryWarning() {
         super.didReceiveMemoryWarning()
         // FIXME:这里做出修改
     }
    

    TUDO注释效果展示
    3. FIXME:

    override func didReceiveMemoryWarning() {
        super.didReceiveMemoryWarning()
        // FIXME:这里做出修改
    }
    

    FIXME:注释展示
    

    Swift的提醒注释做的更加人性化也更加美观，并且从快速跳转区可以很直观的看出来代码的结构。最重要的是它的提醒警告注释不会出现黄色警告标识，这对于我这种重度强迫症真的是福音。
    Swift注释不会出现警告提醒！
    Swift注释不会出现警告提醒！
    Swift注释不会出现警告提醒！
    重要的事情说三遍！！！！！