Google C++ 编程风格：注释【黑马C++培训】

注释虽然写起来很痛苦, 但对保证代码可读性至关重要. 下面的规则描述了如何注释以及在哪儿注释. 当然也要记住: 注释固然很重要, 但最好的代码本身应该是自文档化. 有意义的类型名和变量名, 要远胜过要用注释解释的含糊不清的名字.

你写的注释是给代码读者看的: 下一个需要理解你的代码的人. 慷慨些吧, 下一个人可能就是你!

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

• 函数的输入输出.
• 对类成员函数而言: 函数调用期间对象是否需要保持引用参数, 是否会释放这些参数.
• 如果函数分配了空间, 需要由调用者释放.
• 参数是否可以为 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;// Returns true if the table cannot hold any more entries.bool IsTableFull();

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;

// Divide result by two, taking into account that x// contains the carry from the add.for (int i = 0; i < result->size(); i++) {    x = (x << 8) + (*result);    (*result) = x >> 1;    x &= 1;}
// If we have enough memory, mmap the data portion too.mmap_budget = max<int64>(0, mmap_budget - index_->length());if (mmap_budget >= data_size_ && !MmapData(mmap_chunk_bytes, mlock))    return;  // Error already logged.DoSomething();                  // Comment here so the comments line up.DoSomethingElseThatIsLonger();  // Comment here so there are two spaces between                                // the code and the comment.{ // One space before comment when opening a new scope is allowed,  // thus the comment lines up with the following comments and code.  DoSomethingElse();  // Two spaces before line comments normally.}bool success = CalculateSomething(interesting_value,                                  10,                                  false,                                  NULL);  // What are these arguments??bool success = CalculateSomething(interesting_value,                                  10,     // Default base value.                                  false,  // Not the first time we're calling this.                                  NULL);  // No callback.const int kDefaultBaseValue = 10;const bool kFirstTimeCalling = false;Callback *null_callback = NULL;bool success = CalculateSomething(interesting_value,                                  kDefaultBaseValue,                                  kFirstTimeCalling,                                  null_callback);// 现在, 检查 b 数组并确保 i 是否存在,// 下一个元素是 i+1....        // 天哪. 令人崩溃的注释.

// TODO(kl@gmail.com): Use a "*" here for concatenation operator.// TODO(Zeke) change this to use relations.