《C++面向对象高效编程（第2版）》——3.11 类名、成员函数名、参数类型和文档...
本节书摘来自异步社区出版社《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这可能出人意料，但是许多类确实依赖客户所提供的某些服务。
本文仅用于学习和交流目的，不代表异步社区观点。非商业转载请注明作译者、出处，并保留本文的原始链接。
相关文章：
一个GDIPlus的Bug -- OutofMemory异常
今天发现 framework2.0中的一个GDIPlus的Bug: 在Form的OnPaint事件里面写如下代码： private void Form1_Paint(object sender, PaintEventArgs e) { Pen p new Pen(Color.Red); p.Width 1; p.DashStyle DashStyl…
前后端分离的探索（五）
文桥，13级机械工程系，机械电子工程专业，大四学生。在LSGO软件技术团队负责前端部分，本图文是介绍目前流行的前后端分离技术的第五篇（一共六篇），希望大家能够对这块有所了解。
从一道面试题分析Thread.interrupt方法
阿里面试题： public class TestThread {public static void main(String[] args) {Thread t1 new Thread() {Overridepublic void run() {try {int i 0;while (i < 100000000) {// nothing}System.out.println("A1");} catch (Exception e) {System.…
对联广告，带关闭，可以移动
在网页中加入以下代码 两个图的，一个是关闭用到的，一个是广告图 <script languageJavaScript src"js/scroll.js"></script> js代码如下： suspendcode"<DIV idlovexin1 styleZ-INDEX: 10; LEFT: 6px; POSITION…
u一点·料：阿里巴巴1688ued体验设计践行之路. 导读
U一点料 阿里巴巴1688UED体验设计践行之路 阿里巴巴1688用户体验部著 前言 既赶路，也感受路 文 / 汪方进 用户体验设计师作为一个职能岗位，在国内互联网公司中存在已有十几年的时间了，早期的互联网公司设计师大都是无所不能的多面手ÿ…
Matlab与线性代数 -- 显示格式的设置
打磨一项技能最需要的就是耐心，我们知道做一件事情不会一蹴而就，需要长时间的积累。关于Matlab的打磨会持续很长的时间，每天学习一个知识点，一年下来就不得了。要有耐心，要有耐心，跟着小编每天花5分钟的时间…
java初始化顺序
java初始化顺序
值得收藏的经典网页代码(1)
1. 将彻底屏蔽鼠标右键,无右键菜单 <body οncοntextmenu"event.returnfalse"> 也可以用于网页中Table框架中：<table border οncοntextmenureturn(false)><td>no</table> 2.取消选取、防止复制 <body onselectstart"r…
五款漂亮的 GNOME 3.4 主题-PPA
国外著名开源网站WebUpd8已经把这五款漂亮的Gnome 3.4 的主题制作了PPA，可使用命令轻松实现安装。先来看看这几款主题的截图： adwaita-x-dark Adwaita X dark adwaita-x-light Adwaita X light evolve-gtk3 Evolve theme-ambiance-precise Ambiance-Prec…
Matlab与线性代数 -- 矩阵的加法与减法
打磨一项技能最需要的就是耐心，我们知道做一件事情不会一蹴而就，需要长时间的积累。关于Matlab的打磨会持续很长的时间，每天学习一个知识点，一年下来就不得了。要有耐心，要有耐心，跟着我们每天花5分钟的时间…
备考ocjp有感
看网上好多评论，说什么ocjp的证书很水，复习个一两天，背背题库就能过了。看了之后，有一些感想。 首先，有证书不代表什么，不能说你获得的什么证书，就一定有怎样的能力，有证书不代表什…
买了《精通spring 2.0》
刚才去书店选书，对比了好几本，最后选了这一本。听说第一版有些问题，不过感觉这一版本还可以。理论和实践都有所兼顾。书中的例子是spring自带的例子。转载于:https://www.cnblogs.com/chenge/archive/2007/06/06/774212.html
探索“小数”在计算机中的存储
本文介绍了小数在计算机中的存储方式，第一种为定点方式，这种方式很少遇到，但在Matlab中有涉及，见图文《Matlab与线性代数–显示格式的设置》。第二种为浮点方式，一个浮点数由阶码和尾数构成，一旦明白其中的…
《ELK Stack权威指南（第2版）》一3.8 Docker日志
本节书摘来自华章出版社《ELK Stack权威指南（第2版）》一书中的第3章，第3.8节，作者 饶琛琳 更多章节内容可以访问云栖社区“华章计算机”公众号查看。 3.8 Docker日志 Docker是目前大规模互联网基础架构解决方案中最热门的技术。…
为什么匿名内部类参数必须为final类型
转自：http://ldzyz007.iteye.com/blog/844380 基础语法：如果定义一个匿名内部类，并且希望它使用一个在其外部定的对象，那么编译器会要求其参数引用是final的。 1.匿名内部类肯定是局部内部类(在一个方法里面定义的内部类)&…
开始升级我的工作流系统
终于做完了自定义工作流审批系统的第一个版本，可以说是熬完的，因为真的费了不少力气。不过也慢慢发现设计和实现中的很多问题，便想把它改进一下，改为用.net2.0和sql server2005开发，并想遵从一定的xpdl规范来定义流程。…
《Python和Pygame游戏开发指南》——2.16 pygame.display.update()函数
本节书摘来自异步社区《Python和Pygame游戏开发指南》一书中的第2章，第2.16节，作者[美]Al Sweigart（斯维加特）， 李强 译，更多章节内容可以访问云栖社区“异步社区”公众号查看。 2.16 pygame.display.upda…
Matlab与线性代数 -- 数组的乘法与除法
打磨一项技能最需要的就是耐心，我们知道做一件事情不会一蹴而就，需要长时间的积累。关于Matlab的打磨会持续很长的时间，每天学习一个知识点，一年下来就不得了。要有耐心，要有耐心，跟着我们每天花5分钟的时间…
java实现线性表的顺序存储
今天复习数据结构，按照疯狂java，自己敲了一遍线性表的顺序存储，为了下次看方便，在这里保留一份。 package mysequence;import java.util.Arrays; /*** author lirui* param <T>*/ public class SequenceList<T> {priv…
.Net Framework 3.0 概述
Microsoft .NET Framework 3.0, the managed programming model for Microsoft Windows, includes the .NET Framework 2.0, Windows Presentation Foundation, Windows Communication Foundation, and Windows Workflow Foundation.Microsoft Windows托管编码模型,Microsoft .…
《ABAQUS 6.14超级学习手册》——1.2 ABAQUS分析模块
本节书摘来自异步社区《ABAQUS 6.14超级学习手册》一书中的第1章，第1.2节,作者： 齐威 更多章节内容可以访问云栖社区“异步社区”公众号查看。 1.2 ABAQUS分析模块 ABAQUS包括三个主要的分析模块：ABAQUS/Standard、ABAQUS/Explicit和ABAQUS/…
离散型随机变量的分布律
孔令才，中科院博士，长期致力于传染病空间传播机理的研究。非常开心，他能够加入进来与大家一起分享概率论与数理统计方面的知识。 微信公众平台通常让大家的知识碎片化，而我们要做的事情就是在学习方法论、软件开发、机器学习和数…
带头结点的线性表的链式实现
复习了顺序实现后，自己模仿着写了链式实现 /*** author lirui 带头结点的线性表的链式实现*/ public class MyLinkList<T> {// 内部类LNode,代表链表结点class LNode {private T data;private LNode next;public LNode() {}public LNode(T data, LNode next) …
《 硬件创业：从产品创意到成熟企业的成功路线图》——导读
前言这是一本关于硬件创业的书。本书的目的是为创客们和硬件企业家们提供一张可将产品创意成功转化为成熟企业产品的路线图。软件创业的方式在过去的五年里已经很大程度上模式化了。有各种免费的工具帮助软件企业家们迅速创建公司、展开协作、进行部署和调控；此外&a…
Matlab与线性代数 -- 矩阵的乘法
打磨一项技能最需要的就是耐心，我们知道做一件事情不会一蹴而就，需要长时间的积累。关于Matlab的打磨会持续很长的时间，每天学习一个知识点，一年下来就不得了。要有耐心，要有耐心，跟着我们每天花5分钟的时间…
一个 .net 程序员的梦想！大哥们帮帮我好吗？
我是一个刚学 .net 编程不久的程序员，我特别喜欢用 .net ，一心想建一个.net初学者程序示例网，网站宗旨是：注册后每一个程序员都可以在上面发表自己的程序示例，这样为 .net初学者提供一个很好的学习网，由于本…
用父节点表示法表示一棵树
今天学习，把书上的代码自己边对照，边敲了一下。 package mytree;import java.util.ArrayList; import java.util.List;/*** 用父节点表示法表示一棵树。* * author lirui* param <E>*/ public class TreeParent<E> {public static class Nod…
AJAX学习基础：简单介绍数据岛使用方法
数据岛指的是存在Html网页中的xml代码段，它在Html中形成了一个数据的集合，数据岛允许我们在Html网页中集成xml，对xml编写脚本. 数据岛有它特有的形式，由标记xml开始，在开始标记中要有一个ID属性，用于指定…
《UG NX8.0中文版完全自学手册》一第1章 UG NX 8.0简介
本节书摘来自异步社区《UG NX8.0中文版完全自学手册》一书中的第1章，作者 刘昌丽 , 周进，更多章节内容可以访问云栖社区“异步社区”公众号查看 第1章 UG NX 8.0简介 UG NX8.0中文版完全自学手册UG（Unigraphics）是Unigraphics Sol…
自己动手设计RESTful API
文桥，13级机械工程系，机械电子工程专业，大四学生。在LSGO软件技术团队负责前端部分，本图文是介绍目前流行的前后端分离技术的最后一篇（一共六篇），也是对以前技术进行归纳后用于实战的一篇&#…