你是否在每个.hpp/.cpp文件的顶部添加信息？

Question

当创建一个新的C++头文件/源文件时，你会在顶部添加什么信息？例如，你会添加日期、你的名字、文件描述等吗？你会使用结构化格式来记录这些信息吗？

例如：

// Foo.cpp - Implementation of the Foo class
// Date: 2008-25-11
// Created by: John Smith

我知道有一个团队将CVS提交消息嵌入到每个文件的底部，但我不确定我是否想要这样做...

- Rob

Answer 1

关于文件的创建者、编辑者以及编辑时间等信息，都在源代码控制中心。如果你的团队有良好的提交注释规范，你也可以知道每次更改的原因。不需要为这些内容添加注释。

我认为，完全可以添加注释块来解释类/模块的目的，只要必要就行了。这样，当下一个人去更改它时，他们会更好地了解整体愿景，以及这个文件是否适合他们的更改。

一些商店在源文件注释中加入版权声明和其他法律废话。这让我觉得很傻 - 如果你的（非开源）源代码在未经你的知识或许可的情况下被放到了别人的服务器上，版权声明可能并不能阻止他们做任何事情。我不是律师，你的情况可能不同。

- bradheintz

---

法律声明的目的是让用户知道它属于谁，仅此而已。 - Marcin

如果你的店里有人在使用代码，但不清楚它来自哪里，那可能是个问题。另一方面，如果你的（非开源）源代码离开了你的网络，那么你面临的问题比版权侵犯更大。 - bradheintz

我可以理解这是一种自我保护措施，如果你的代码不慎落入了错误的手中，你可以向法官证明你已经尽力去表明这份代码是专有的，即使这种努力看起来很傻或者无效。但我认为更好的方式是使用源代码控制日志。 - bradheintz

Answer 2

不需要。大多数东西在需要时都可以从版本控制系统中检索，因此添加是多余的。这将使您拥有文件内容的描述，但大多数情况下这是类文档的一部分（或至少是特定类型的文档）。我不做这些事情，但再说一遍，我不喜欢这些累赘。

- Jasper Bekkers

---

并非所有的程序都是用类编写的。有些程序仍然具有实用代码，未分类的函数被聚集在一起等等。至少要有一个简短的文件描述是很好的。 - Chris Charabaruk

并非每个人都可以使用版本控制系统 - 特别是如果代码是作为源代码分发的，而不是版本文件。 - Jonathan Leffler

Answer 3

我会在文件名中包含一个简短的描述，说明文件的目的，并添加一个$Id$标记，以便于CVS或Subversion使用。文件的创建者和创建日期可以通过检查存储库来找到，因此不需要在文件中包含这些信息。

包含文件名是因为在编辑文件时，有时可能无法完全确定文件名。描述可以用于确定代码段是否应该放在文件中，或者是否应该移动到其他文件中。当然，$Id$可以告诉你最后一次更改时间和最后一位编辑者。

仅在提交消息有用时才将其嵌入代码中，而且仅在文件偶尔更新时才有用。包含每个提交消息只会使文件膨胀到评论描述更改的数量超过实际代码的数量。最好也将其留给存储库；通常只需要一个简短的命令行即可获取文件的提交日志。

如果您使用的版本控制系统不能保留移动和复制的历史记录，在这种情况下，只需引用原始文件及其版本号即可。当然，如果您使用的是本世纪而不是上个世纪创建的系统，这不应该成为问题。

- Chris Charabaruk

Answer 4

我们需要在每个文件的顶部放置版权信息。我认为日期、作者和文件名是浪费时间的。

我们的源代码控制系统还会在每个文件的底部附加提交注释。我最初讨厌变更日志，但随着时间的推移，我学会了喜欢它。当合并更改时，它确实很有帮助。

- Aardvark

---

将变更日志粘贴在文件底部是正确的做法，如果无法避免的话。 - Chris Charabaruk

Answer 5

原本在这里回答，但已被删除：134249

我只会放两件事：

• 许可证/版权信息
• 文档生成工具所需的注释（即，注释必须在头文件中才能起作用 - 否则，它们应该放在定义文件中）

其他任何东西都是不必要的废话，不会得到维护，并最终变得比没有更糟。

当时我在一家大型国防公司工作，我们有苛刻的编码标准。如果你完全遵循它们（大多数人不会），那么你的大部分头文件将由那些毫无意义的废话组成。更糟糕的是，相同的废话也需要放在源文件中，这意味着两份废话过时了并且变得误导人。

- Ben Collins

Answer 6

我曾经喜欢在文件头部放置版本控制关键字，但已经从这种困扰中恢复过来了。:) 有两个原因：

1. 没有人放置有用的注释。你总是会查看版本控制系统报告的差异。
2. 它会在尝试对大型文件集进行差异比较时创建一个噩梦，因为关键字会创建文件中唯一的差异。

- Steve Fallows

Answer 7

我不嵌入日期是因为这是多余的。如果有人想知道文件创建的日期，不要信任作者，请信任您的源代码管理系统。它应该是文件创建日期的确定答案。

我绝对不反对嵌入检查消息。那些非常有用。

- JaredPar

---

在看到有10多年CVS消息的文件后，它们可能会有点难以浏览。 :) - Rob

@JaredPar：对于日期，如果源代码是分布式的但不包括版本控制系统文件，则没有可信赖的版本控制系统 - 在文件中嵌入日期是有益的。 - Jonathan Leffler

Answer 8

如果您正在使用CVS，请查看其关键字替换。它们将有助于自动嵌入该信息。

个人而言，我会将此放在所有源文件的顶部：

// $Id$

如果其他信息性注释与某些特定内容（文件、类、类型等）相关，则我将它们嵌入到doxygen中以进行解析。

- luke

Answer 9

我们使用RCS自动在文件上打以下标记：

版权信息，

RCS文件名，

修改日期，

最后修改的作者，

RCS版本号

我认为这非常方便。 我真的喜欢每个文件中都自动填充文件名，因为它使得查找文件变得非常快速。

- Marcin

Answer 10

这是我通常放在文件顶部的内容：

///////////// Copyright © 2008 DesuraNET. All rights reserved. /////////////
//
//   Project     : [project name]
//   File        : [file name]
//   Description :
//      [TODO: Write the purpose of ... ]
//
//   Created On: 11/12/2008 2:24:07 PM
//   Created By: [name] <mailto:[email]>
////////////////////////////////////////////////////////////////////////////

我在Vis中设置了一个宏，以便在创建新文件时添加并填写默认信息。

- Lodle