C++ 编程
有很多很好的理由去文档你的代码，还有很多代码可以被文档化的方面。文档为你提供了一个捷径，让你可以获得系统的概述，或者理解提供特定功能的代码。
注释的目的是向任何检查它的人解释和澄清源代码（或者仅仅作为对你自己的一种提醒）。良好的注释习惯对于任何非平凡的程序来说都是必不可少的，这样阅读代码的人就可以理解它预期做什么，并使代码的其余部分易于理解。在接下来的主题中，将为你列出一些使用注释的 如何？ 和 何时？ 规则。
不仅在 C++ 中，在任何编程语言中，编程的文档都是必不可少的。许多公司已经从“英雄程序员”（即为整个公司编码的单个程序员）的概念转变为团队合作的程序员群体的概念。很多时候，程序员只会在较大型项目的一部分上工作。在这种情况下，文档是必不可少的，因为
- 其他程序员可能被分配开发你的项目；
- 你的完成的项目可能会提交给编辑，以便将你的代码组装到其他项目中；
- 除了你之外的人可能需要阅读、理解和展示你的代码。
即使你不是为了谋生或为了公司而编程，文档你的代码仍然是必不可少的。尽管许多程序可以在几个小时内完成，但更复杂的程序可能需要更长的时间才能完成（天、周等）。在这种情况下，文档是必不可少的，因为
- 你可能无法在一个会话中完成你的项目；
- 它提供你上次编程时所做更改的参考；
- 它允许你记录你做出决定的 原因，包括为什么你选择 不 探索某些解决方案；
- 它可以提供一个记录已知限制和错误的地方（对于后者，缺陷跟踪系统可能是文档的合适地方）；
- 它允许在程序中轻松搜索和引用（从非技术角度）；
- 它被认为是良好的编程实践。
注释应该针对合适的受众。当编写代码供那些处于学习新编程语言初始阶段的人阅读时，包含大量关于代码功能的注释可能会有所帮助。对于“生产”代码，由专业人士阅读的代码，包含已经清楚地显示在代码中的注释被认为是无用且适得其反的。来自 极限编程 社区的一些人说，过多的注释表明存在 代码异味 -- 这并不意味着注释不好，而是它们通常是代码需要 重构 的线索。将注释作为编写可理解代码的替代方案被认为是不好的做法。
在程序/源代码中需要文档化的内容可以分为在特定程序执行之前（即在“main”之前）文档化的内容和执行的内容（“main 中的内容”）。
程序执行之前的文档
- 程序员信息和许可证信息（如果适用）
- 用户定义的函数声明
- 接口
- 上下文
- 相关标准/规范
- 算法步骤
- 如何将源代码转换为可执行文件（也许使用 make）
main 内部代码的文档
- 语句、循环和情况
- 类内的公共和私有部分
- 使用的算法
- 实现的异常特征
- 避免其他选择的理由
- 用户定义的函数实现
如果使用不当，注释会使源代码难以阅读和维护，并且如果代码是自解释的，注释甚至可能是多余的 -- 但请记住，今天看似自解释的内容在六个月或六年后可能就不一样了。
注释应该文档决策。在你必须做出选择的地方，添加一个注释来描述你做出了什么选择以及原因。考古学家会发现这是最有用的信息。
项目的每个部分都应该至少有一个注释布局，最好让整个项目共享相同的布局（如果可能的话）。
文档可以通过使用注释（如上所示）在源代码本身中完成，以目标受众可以理解的语言进行。在英语中进行操作是好的做法，因为 C++ 语言本身是基于英语的，而英语是当前 通用语，用于国际商务、科学、技术和航空，你将确保为最广泛的受众提供支持。
注释对于文档要执行的算法部分、解释函数调用和变量名称或提供使用特定选择或方法的原因很有用。块注释的使用方式如下
/*
get timepunch algorithm - this algorithm gets a time punch for use later
1. user enters their number and selects "in" or "out"
2. time is retrieved from the computer
3. time punch is assigned to user
*/
或者，可以使用行注释，如下所示
GetPunch(user_id, time, punch); //this function gets the time punch
一个使用注释作为文档的完整程序示例如下所示
/*
Chris Seedyk
BORD Technologies
29 December 2006
Test
*/
int main()
{
cout << "Hello world!" << endl; //predefined cout prints stuff in " " to screen
return 0;
}
需要注意的是，虽然注释对于程序内文档很有用，但最好也有一种与源代码分离的外部文档形式，但请记住在代码注释中参考外部信息之前先考虑源代码的发布方式。
注释代码也不能替代经过精心策划的、有意义的变量、函数和类名称。这通常被称为“自文档化代码”，因为很容易从精心选择的描述性名称中看出变量、函数或类的作用。为了说明这一点，请注意以下两种文档化代码的方式的相对简单的程度，尽管第一种使用了注释，而第二种没有使用注释，但都易于理解。第一种风格经常出现在非常老的 C 源代码中，编写者非常清楚他们在做什么，并且毫无疑问其他人可能不理解它。第二种风格更“人性化”，虽然更容易阅读，但并不像以前那样频繁地遇到。
// Returns the area of a triangle cast as an int
int area_ftoi(float a, float b) { return (int) a * b / 2; }
int iTriangleArea(float fBase, float fHeight)
{
return (int) fBase * fHeight / 2;
}
这两个函数执行相同的任务，但第二个函数为函数和变量选择了如此实用的名称，以至于即使没有注释，其目的也很清楚。随着代码复杂度的增加，精心选择的命名方案变得越来越重要。
无论采用何种方法，代码中的注释都有助于节省时间（和头痛），并确保作者和其他人充分理解程序的布局和目的。
有多种工具可以帮助您记录 C++ 代码；文学化编程 是一种完整的编程理念，但一个非常有效的工具是 Doxygen（也支持多种语言），它甚至可以使用手写的注释来生成超过代码基本结构的内容，将类似 Javadoc 的文档注释引入到 C++ 中，并且可以生成 HTML、PDF 等格式的文档。
将您的注释视为一个描述系统的故事。假设您的注释会被机器人提取并整理成手册页面。类注释是故事的一部分，方法签名注释是另一部分，方法参数是另一部分，方法实现又是另一部分。所有这些部分应该相互交织，并告知其他人，在未来的某个时间点，您究竟做了什么以及为什么这样做。
- 不要使用注释来绘制流程图或编写伪代码
您应该避免使用注释来绘制 ASCII 艺术或编写伪代码（一些程序员尝试使用 ASCII 艺术流程图来解释他们的代码）。如果您想绘制流程图或以其他方式对您的设计进行建模，可以使用其他工具，这些工具将使用标准化方法更好地完成这项工作。例如，参见：UML。