Google C++编程气势指南（六）:代码注释[VC/C++编程]

注释

注释固然写起来很痛楚,但对保证代码可读性至为重要,下面的法则描写了应当注释什么、注释在哪儿.当然也要记着,注释的确很重要,但最好的代码本身就是文档（self-documenting）,范例和变量命名意义明确要比通过注释注释模糊的命名好得多.

注释是为别人（下一个需求理解你的代码的人）而写的,认真点吧,那下一个人大概就是你!

1.注释气势（Comment Style）

利用//或/* */,统一就好.

//或/* */都可以,//只是用的越发遍及,在若何注释和注释气势上确保统一.

2.文件注释（File Comments）

在每一个文件开首加入版权告示,然后是文件内容描写.

法律告示和作者信息:

每一文件包含以下项,顺次是:

1) 版权（copyright statement）:如Copyright 2008 Google Inc.;

2) 答应版本（license boilerplate）:为项目挑选符合的答应证版本,如Apache 2.0、BSD、LGPL、GPL;

3) 作者（author line）:标识文件的原始作者.

假如你对其他人成立的文件做了庞大改正,将你的信息增添到作者信息里,这样当其他人对该文件有疑问时可以知道该接洽谁.

文件内容:

每一个文件版权答应及作者信息后,都要对文件内容举行注释阐明.

普通,.h文件要对所声明的类的功效和用法作简单阐明,.cc文件包含了更多的实现细节或算法谈论,假如你感受这些实现细节或算法谈论关于阅读有帮忙,可以把.cc中的注释放到.h中,并在.cc中指出文档在.h中.

不要纯真在.h和.cc间复制注释,复制的注释偏离了实际意义.

3.类注释（Class Comments）

每个类的定义要附着描写类的功效和用法的注释.

// 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 {
...
};

假如你认为已经在文件顶部具体描写了该类,想直接简单的来上一句“完好描写见文件顶部”的话,还是多少在类中加点注释吧.

假如类有任何同步前提（synchronization assumptions）,文档阐明之.假如该类的实例可被多线程拜候,利用时务必注意文档阐明.

　　以上是“Google C++编程气势指南（六）:代码注释[VC/C++编程]”的内容，如果你对以上该文章内容感兴趣，你可以看看七道奇为您推荐以下文章：