深入了解C++注释包括哪些类型?

开课吧小一2021-06-15 11:40

    众所周知作为一名合格的C++开发工程师,应该明白注释虽然写起来很痛苦,但对保证代码可读性至关重要。为了能够做好C++注释,需要深入了解C++注释包括哪些类型?

深入了解C++注释包括哪些类型?

    深入了解C++注释包括哪些类型?

    一般来说C++注释的类型包括以下这些:

    1、函数注释:函数声明处注释描述函数功能;定义处描述函数实现。

    函数声明:注释位于声明之前,对函数功能及用法进行描述。注释使用叙述式(“Opensthefile”)而非指令式(“Openthefile”);注释只是为了描述函数,而不是命令函数做什么。通常,注释不会描述函数如何工作。那是函数定义部分的事情。

    函数声明处注释的内容:函数的输入输出。

    对类成员函数而言:函数调用期间对象是否需要保持引用参数,是否会释放这些参数。

    如果函数分配了空间,需要由调用者释放。

    参数是否可以为NULL。

    是否存在函数使用上的性能隐患。

    如果函数是可重入的,其同步前提是什么?

// Returns an iterator for this table.  It is the client's
// responsibility to delete the iterator when it is done with it,
// and it must not use the iterator once the GargantuanTable object
// on which the iterator was created has been deleted.
//
// The iterator is initially positioned at the beginning of the table.
//
// This method is equivalent to:
//    Iterator* iter = table->NewIterator();
//    iter->Seek("");
//    return iter;
// If you are going to immediately seek to another place in the
// returned iterator, it will be faster to use NewIterator()
// and avoid the extra seek.
Iterator* GetIterator() const;

    但也要避免罗罗嗦嗦,或做些显而易见的说明。下面的注释就没有必要加上“returnsfalseotherwise”,因为已经暗含其中了:

// Returns true if the table cannot hold any more entries.
bool IsTableFull();

    注释构造/析构函数时,切记读代码的人知道构造/析构函数是干啥的,所以“destroysthisobject”这样的注释是没有意义的。注明构造函数对参数做了什么(例如,是否取得指针所有权)以及析构函数清理了什么。如果都是些无关紧要的内容,直接省掉注释。析构函数前没有注释是很正常的。

    函数定义:

    每个函数定义时要用注释说明函数功能和实现要点。比如说说你用的编程技巧,实现的大致步骤,或解释如此实现的理由,为什么前半部分要加锁而后半部分不需要。

    不要从.h文件或其他地方的函数声明处直接复制注释。简要重述函数功能是可以的,但注释重点要放在如何实现上。

    2、类注释:每个类的定义都要附带一份注释,描述类的功能和用法。

// Iterates over the contents of a GargantuanTable.  Sample usage:
//    GargantuanTable_Iterator* iter = table->NewIterator();
//    for (iter->Seek("foo"); !iter->done(); iter->Next()) {
//      process(iter->key(), iter->value());
//    }
//    delete iter;
class GargantuanTable_Iterator {
    ...
};

    如果你觉得已经在文件顶部详细描述了该类,想直接简单的来上一句“完整描述见文件顶部”也不打紧,但务必确保有这类注释。

    如果类有任何同步前提,文档说明之。如果该类的实例可被多线程访问,要特别注意文档说明多线程环境下相关的规则和常量使用。

    3、文件注释:在每一个文件开头加入版权公告,然后是文件内容描述.

    法律公告和作者信息:每个文件都应该包含以下项,依次是:版权声明(比如,Copyright2008GoogleInc.)。

    许可证:为项目选择合适的许可证版本(比如,Apache2.0,BSD,LGPL,GPL)。

    作者:标识文件的原始作者。

    如果你对原始作者的文件做了重大修改,将你的信息添加到作者信息里。这样当其他人对该文件有疑问时可以知道该联系谁。

    文件内容:紧接着版权许可和作者信息之后,每个文件都要用注释描述文件内容.

    通常,.h文件要对所声明的类的功能和用法作简单说明..cc文件通常包含了更多的实现细节或算法技巧讨论,如果你感觉这些实现细节或算法技巧讨论对于理解.h文件有帮助,可以将该注释挪到.h,并在.cc中指出文档在.h.

    不要简单的在.h和.cc间复制注释.这种偏离了注释的实际意义.

    变量注释。通常变量名本身足以很好说明变量用途.某些情况下,也需要额外的注释说明。

    4、变量注释:通常变量名本身足以很好说明变量用途。某些情况下,也需要额外的注释说明。

    类数据成员:

    每个类数据成员(也叫实例变量或成员变量)都应该用注释说明用途。如果变量可以接受NULL或-1等警戒值,须加以说明。比如:

private:
    // Keeps track of the total number of entries in the table.
    // Used to ensure we do not go over the limit. -1 means
    // that we don't yet know how many entries the table has.
    int num_total_entries_;

    全局变量:

    和数据成员一样,所有全局变量也要注释说明含义及用途。比如:

// The total number of tests cases that we run through in this regression test.
const int kNumTestCases = 6;

    5、弃用注释:通过弃用注释(DEPRECATEDcomments)以标记某接口点(interfacepoints)已弃用。

    您可以写上包含全大写的DEPRECATED的注释,以标记某接口为弃用状态。注释可以放在接口声明前,或者同一行。

    在DEPRECATED一词后,留下您的名字,邮箱地址以及括号补充。

    仅仅标记接口为DEPRECATED并不会让大家不约而同地弃用,您还得亲自主动修正调用点(callsites),或是找个帮手。

    修正好的代码应该不会再涉及弃用接口点了,着实改用新接口点。如果您不知从何下手,可以找标记弃用注释的当事人一起商量。

    以上就是小编为大家整理的“深入了解C++注释包括哪些类型?”一文,更多相关信息尽在开课吧C++教程频道。

相关推荐:

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

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

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

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