深入了解C++注释的分类以及案例

开课吧小一2021-06-08 14:48

    众所周知优秀的C++开发工程师,在书写代码的时候,一方面掌握了良好的方式方法,可以有效提高代码的重复使用率,另一方面会做好注释。

深入了解C++注释的分类以及案例

    如何看待程序员不写注释?

    不写注释就是害人害己,别人看不懂,过几天连自己也看不懂;

    好的代码就是最好的注释,我的代码可读性很好,没必要写注释;

    只要有完善的文档,代码本身就是注释;

    自己写代码时:“我自己写的代码还要写注释?”看别人的代码时:“这人居然不写注释?”

    对于程序员群体,有网友的总结非常到位:程序员最讨厌的四件事:1、写注释;2、别人不写注释;3、写文档;4、别人不写文档;不得不说程序员群体真是个可爱而又敢于自黑的群体。

深入了解C++注释的分类以及案例

    如何优雅的为程序写注释?

    “好的代码不需要注释”不等于“没有注释就是好的代码”,好的代码不需要注释的前提是后面阅读你代码的人水平不能比你差太多,要写出那种新人都能看懂的代码,实在是太难了。

    利用好注释模板:注释模板为注释写作提供了极大的便利,我们常用的开发工具如VSCode、Xcode都对注释模板有很好的支持;例如Xcode,只要在需要注释的代码的上一行按下快捷键:「opt+cmd+/」 就可以添加注释模板。

    注释风格://或者///或/**/都可以;但//更常用,要在如何注释及注释风格上确保统一。

    文件注释:文件注释描述了该文件的内容,每个文件注释都要包含以下内容:文件内容的简要描述、作者信息、日期、版权信息声明。

    文件注释的顺序应该如下:

    文件内容的简要描述;

    作者信息;

    日期;

    版权信息声明,例如:Copyright2008GoogleInc。必要的话还可以加上许可证样板,例如:Apache2.0,BSD,LGPL,GPL。

//
//  Kingfisher.swift
//  Kingfisher
//
//  Created by Wei Wang on 16/9/14.
//
//  Copyright (c) 2019 Wei Wang <onevcat@gmail.com>
//
//  Permission is hereby granted, free of charge, to any person obtaining a copy
//  of this software and associated documentation files (the "Software"), to deal
//  in the Software without restriction, including without limitation the rights
//  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
//  copies of the Software, and to permit persons to whom the Software is
//  furnished to do so, subject to the following conditions:
//
//  The above copyright notice and this permission notice shall be included in
//  all copies or substantial portions of the Software.
//
//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
//  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
//  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
//  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
//  THE SOFTWARE.

    类注释:类注释应该要为读者提供使用该类的足够信息,同时应当提醒读者在使用此类时要注意的事项。

import Foundation

/// `Session` creates and manages Alamofire's `Request` types during their lifetimes. It also provides common
/// functionality for all `Request`s, including queuing, interception, trust management, redirect handling, and response
/// cache handling.
open class Session {
 ...
}

    函数注释:我们要在每个函数的声明处前加上注释,描述该函数的功能和用途.只有在函数的功能通俗易懂时才可以省略这些注释(例如:简单的取值和设值函数)。

/// Creates a `DataRequest` from a `URLRequest` created using the passed components and a `RequestInterceptor`.
    ///
    /// - Parameters:
    ///   - convertible:     `URLConvertible` value to be used as the `URLRequest`'s `URL`.
    ///   - method:          `HTTPMethod` for the `URLRequest`. `.get` by default.
    ///   - parameters:      `Parameters` (a.k.a. `[String: Any]`) value to be encoded into the `URLRequest`. `nil` by
    ///                      default.
    ///   - encoding:        `ParameterEncoding` to be used to encode the `parameters` value into the `URLRequest`.
    ///                      `URLEncoding.default` by default.
    ///   - headers:         `HTTPHeaders` value to be added to the `URLRequest`. `nil` by default.
    ///   - interceptor:     `RequestInterceptor` value to be used by the returned `DataRequest`. `nil` by default.
    ///   - requestModifier: `RequestModifier` which will be applied to the `URLRequest` created from the provided
    ///                      parameters. `nil` by default.
    ///
    /// - Returns:       The created `DataRequest`.
    open func request(_ convertible: URLConvertible,
                      method: HTTPMethod = .get,
                      parameters: Parameters? = nil,
                      encoding: ParameterEncoding = URLEncoding.default,
                      headers: HTTPHeaders? = nil,
                      interceptor: RequestInterceptor? = nil,
                      requestModifier: RequestModifier? = nil) -> DataRequest {
        let convertible = RequestConvertible(url: convertible,
                                             method: method,
                                             parameters: parameters,
                                             encoding: encoding,
                                             headers: headers,
                                             requestModifier: requestModifier)

        return request(convertible, interceptor: interceptor)
    }

    变量注释:通常我们取变量名称的时候已经将其意义说明了。但是在逻辑复杂的情况下,还是需要添加一些注释说明来做特别说明。

/// Underlying `URLSession` used to create `URLSessionTasks` for this instance, and for which this instance's
    /// `delegate` handles `URLSessionDelegate` callbacks.
    ///
    /// - Note: This instance should **NOT** be used to interact with the underlying `URLSessionTask`s. Doing so will
    ///         break internal Alamofire logic that tracks those tasks.
    ///
    public let session: URLSession

    TODO注释:对那些临时的,短期的解决方案,使用TODO注释。

// TODO(kl@gmail.com): Use a "*" here for concatenation operator.
// TODO(Zeke) change this to use relations.
// TODO(bug 12345): remove the "Last visitors" feature

    弃用注释。通过注释(「DEPRECATED」 comments)来标记接口已弃用,并要说明后续的替代方案。

/// Gets an image deserialized from provided data.
    ///
    /// - Parameters:
    ///   - data: The data from which an image should be deserialized.
    ///   - options: Options for deserialization.
    /// - Returns: An image deserialized or `nil` when no valid image
    ///            could be deserialized.
    /// - Note:
    /// This method is deprecated. Please implement the version with
    /// `KingfisherParsedOptionsInfo` as parameter instead.
    @available(*, deprecated,
    message: "Deprecated. Implement the method with same name but with `KingfisherParsedOptionsInfo` instead.")
    func image(with data: Data, options: KingfisherOptionsInfo?) -> KFCrossPlatformImage?

    以上就是小编为大家整理的“深入了解C++注释的分类以及案例”一文,更多相关信息尽在开课吧C/C++教程频道。

相关推荐:

2021大厂高频面试题精选,0元免费领

福利来袭,C++经典项目实战免费领取!

职场进阶必备,数据分析职业能力特训营

免责声明:本站所提供的内容均来源于网友提供或网络搜集,由本站编辑整理,仅供个人研究、交流学习使用。如涉及版权问题,请联系本站管理员予以更改或删除。
有用1
分享