C++程序设计风格和文档

参考资料：C++程序设计补充资料I.E

所谓的程序设计风格（programming style），就是如何安排程序的外观样式。即使我们把一个程序写成只有一行的形式，它也完全可以正确编译和运行，但“一行程序”是一种不好的程序设计风格，因为这样的程序难读、难理解。文档（document）就是附属程序的说明性注释。程序设计风格和注释与编码同样重要。好的程序设计风格和适当的文档会降低发生错误的可能性，使程序更为易读。

课文实例：显示当前时间

// 实例：显示当前时间
#include <iostream>
#include <ctime>
using namespace std;

int main()
{
// Obtain the total seconds since the midnight, Jan 1.1970
int totalSecomds = time(0);

// Compute the current second in the minute in the hour
int totalSecond = totalSecomds % 60;

// Obtain the total minutes
int totalMinutes = totalSecomds / 60;

// Compute the current minute in the hour
int totalMinute = totalMinutes % 60;

// Obtain the total hours
int totalHours = totalMinutes / 60;

// Compute the current hour
int currentHour = static_cast<int>(totalHours % 24);

// Display results
cout << "Current time is " << currentHour << ":"
<< totalMinute << ":" << totalSecond << " GMT" << endl;

system("pause");
return 0;
}

适当的注释和注释风格

在程序的开始部分，我们应该给出一段摘要，简要描述这个程序要做什么、它的关键特性、它支持的数据结构以及它所使用的独特的技术。在一个较长的程序中，我们还应该加入一些注释，介绍程序的主要步骤，解释每一个难于理解的地方。注释简洁明了是很重要的，以免使程序显得臃肿或难以理解。
要注释一个
4000
函数内的步骤，使用行注释（//）。

变量和常量的命名
就像现实世界中的每一个实体都有名字一样，我们应该为程序中所使用的实体起一个名字。程序设计语言使用称为标识符（identifier）的特殊符号为变量、常量及函数等程序实体命名。标识符命名的规则如下：

一个标识符是一个字符序列，可以包含字母、数字和下划线(_)。
一个标识符必须以一个字母或一个下划线开头，不能以字母开头。
不能使用保留字（也叫关键字）作为标识符。
一个标识符理论上可以任意长，但我们使用的具体的C++编译器可能会有限制，使用31个字符或者更短的标识符可保证程序的可移植性。
对于类名称，大写名称中每个单词的第一个字母；例如，类名ComputeArea。

注由于C++是大小写敏感的，因此，X与x是不同的标识符。

习惯上，变量名使用小写字母。如果一个变量名由多个单词组成，则将每个单词的第一个字母大写（第一个单词除外），然后将它们串接起来。例如，radius和interestRate。
习惯上，常量的名字用大写——PI和MAX_VALUE。一个常量必须在一条语句中声明并初始化

提示标识符用于命名变量、函数及程序中其他实体。有意义的描述性标识符会使程序更为易读。除了选择描述性的名字这一基本原则外，C++还有一套约定俗成的针对不同种类标识符的命名习惯。

     警告不要使用以下划线开头的标识符，以免混淆，因为C++编译器可能为一些内部实体使用这类名字。

恰当的缩进和空白

在程序中使用一致的缩进风格，会使程序更为清晰易读。缩进（indentation）的作用是显示程序组件或语句之间的语法结构关系。即使一个程序的所有语句都放在一行内，C++编辑器也能正确分析，但是，如果能恰当地对齐语句，那么代码的可读性和可维护性就会更好。一种较好的方式是每一个子结构/语句比其父结构（嵌入的结构）缩进两个空格。

在二元运算符的两边应该各放置一个空格，如下面语句所示：

bool b = 3 + 4 * 4 > 5 * (4 + 3) - ++i;

使用空格分隔函数中的参数。不要在函数中的括号之前或之后留空格，例如：

aFunction(A1,
A2)比aFunction( A1, A2 )更符合规范。

     在代码片段之间应该各放置一个空格，以使程序更为清晰易读。

块风格

块是由括号包围的一组语句。块可以以多种方式编写。例如，以下是等效的：

int main()
{
// Display Welcome to C++ to the console
cout << "Welcome to C++!" << endl;
return 0;
}

int main() {
// Display Welcome to C++ to the console
cout << "Welcome to C++!" << endl;
return 0;
}

前者被称为下行样式，而后者，作为结束行样式。下行块样式用于C
++程序，而结束行样式通常优先用于Java程序。

if-else Style

  if (cond1)

{

// Statements

}

else if (cond2)

{

// Statements

}

else if (cond3)

{

// Statements

}

else

{

    // Statements

  }

for loop Style

  for (int i = 1; i < n; i++)

{

    // Statements

  }

while loop Style

  while (i < n)

{

    // Statements

  }

do-while loop Style

  do

{

    // Statements

  }while (i < n);

try-catch Style

  try

{

    // Statements

  }

catch (Exception ex)

{

// Handler

} 

Summary

Use line comments to describe steps inside a function.（使用行注释来描述函数内的步骤）
Indent your statement two spaces.（缩进你的语句两个空格）
Use Next-Line style.（使用下行样式）
Leave a blank line before a comment line or a comment paragraph.（在注释行或注释段之前留空行）