本节书摘来自异步社区出版社《C++面向对象高效编程（第2版）》一书中的第3章，第3.11节，作者： 【美】Kayshav Dattatri，更多章节内容可以访问云栖社区“异步社区”公众号查看。

3.11 类名、成员函数名、参数类型和文档

C++面向对象高效编程（第2版）
类通常被另一个程序员用来创建对象（或者通过继承创建其他类），而方法则被这些对象（可能提供参数）调用。我们不仅要为类和其中所包含的方法提供有意义的名称，还应该为成员函数的参数使用合适的名称，这样，客户可以清楚地知道某个特别参数的用途。许多程序员只指明函数接受的参数类型，而不给出名称，必须改掉这个坏习惯。当然，编译器不会在意你选择什么名称，它只负责匹配类型。但是，参数名可以向客户传达许多信息。除此之外，我们还要注意使用正确的参数传递模式（值、引用或指针）。

在大多数情况下，仅通过查看名称，无法清楚地了解类及其成员函数的用途。我们必须提供详尽的文档（documentation），其内容包括：

类的用途
预定用户（打算给谁使用）
它所依赖的类（如果有）
类的限制是什么
它期望从客户方面获得什么1
在多线程系统中，还要进一步说明在多线程执行的环境中，类是否可用，这非常重要。大多数公司、项目和架构都要求类的设计者和实现者提供更多详细的文档。在设计和为类编写文档时，遵循所有的指导原则非常重要。

还有一点也至关重要，类的设计者（和实现者）必须非常清楚地说明创建对象的限制条件。例如，某些类要求只能在运行时栈中创建类的对象（以确保自动销毁）；而另一个类可能限制只能在动态堆上创建对象（即对象必须只能用new操作符创建）。这些对创建对象的限制不是很常见，但是，如果遇到也不必惊讶。用文档说明创建对象的限制是个不错的主意，但并不是最佳方案，最好是能通过语言强制执行这些限制。在C++中，控制对象在何处创建非常容易。实现它们的技巧将在第11章中介绍。

类中包含的每种方法，都需要一个类似的说明文档。类文档（class documentation）将客户的注意力集中在一个方向，而且每种方法的文档（或说明）进一步阐明了该方法在类中完成的工作。这样的文档不应该是一本厚厚的书，它可以是头文件中的简单注释（对于简单方法），或是和类一起提供的辅助文档。大文档会让客户感到害怕，他们担心类太复杂，难以理解（客户认为正是这些原因导致需要大的文档），因此不愿意使用它。一个设计优秀并带有适宜说明的类将吸引客户的注意力，并鼓励她们使用。这类似于一个维护良好的公园，它引诱你入园漫步。在头文件中作简明扼要的注释非常有用，因为大多数程序员会首先在头文件中查找信息。此外，每种方法也应指明它所接受的每个参数的用途。在使用引用和指针（大多数是指针）的情况下，必须清楚地定义存储区所有权的职责（ownership responsibility），否则，会导致内存泄漏或运行时崩溃，扰乱系统程序的正常运行。事实上，大部分与资源相关的问题都是由于类的实现者和用户未明确各自的职责引起的。当方法返回值（引用，指针或值）给调用者时，也需要明确地定义存储区所有权职责。要养成尽可能使用const参数和const成员函数的习惯，因为编译器能识别const元素，而且const可防止意外的修改。语言不能阻止恶意用户的所作所为，它只能防止用户在使用时出现的意外错误。

你可能会问，为什么要对文档和参数传递如此小题大做？为什么不能让编译器来处理这一切？问题是，很多程序员可以完成的事情，编译器根本检测不到。编译器无法读取你的想法，也不知道函数声明中某个参数的用途。编译器所能见的只是类型名，它根本不关心函数的参数名。但是，对我们而言，这些参数名有实际意义。作为程序的设计者，我们在设计中将特定议题作为目标，并尝试解决一些问题。编译器完全不明白这些议题，对它而言，任何程序都是一系列的指令而已，它无法知晓“设计蓝图”。这就是文档、约定（convention）和指导原则发挥作用的地方。

1这可能出人意料，但是许多类确实依赖客户所提供的某些服务。
本文仅用于学习和交流目的，不代表异步社区观点。非商业转载请注明作译者、出处，并保留本文的原始链接。