Question

在创建新的C ++标头/源文件时，您将哪些信息添加到顶部？例如，您是否添加了日期，您的姓名，文件说明等？您是否使用结构化格式来获取此信息？

e.g。

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

我认识的一个团队将CVS提交消息嵌入到每个文件的脚下，但我不确定我是否想要走这么远......

Answer 1

有关创建文件的人员以及编辑文件的时间和人员的信息以及何时全部都在源代码管理中。如果您的团队在签到评论方面有良好的做法，那么您也会知道每次更改的原因。不需要对那些东西发表评论。

我认为100％合法 - 甚至 - 只要有必要，就可以用一个注释块来解释类/模块的目的。当下一个人去改变它时，他们会更好地了解整体愿景以及这个档案是否适合他们改变。

Answer 2

别。大多数东西都可以在需要时从版本控制系统中检索，因此添加多余。这将留下您对文件内容的描述，但这大部分时间都是类文档的一部分（或者至少是特定类型的文档）。

我不做其中的任何一件事，但话又说回来，我不喜欢这件事。

Answer 3

我包含文件名，文件用途的简要说明，以及用于CVS或Subversion目的的$ Id $标记。通过检查存储库可以找到文件创建者和创建日期，因此不需要它。

包含文件名，因为根据您用来编辑文件的内容，在编辑文件时可能并不完全明显。该描述可用于确定一些代码是否属于该文件，或者是否应将其移动到另一个。当然，$ Id $会给你最后一次更改时间和最后一位编辑。

嵌入签到消息仅在消息有用时才有用，并且仅在文件更新一次时才有用。包含每条消息只会使文件膨胀到有更多注释描述更改而不是实际代码的程度。最好将它留给存储库;通常它只是一个简短的命令行来获取文件的登记日志。

如果您遇到无法保留移动和副本历史记录的修订控制系统，那么只需引用原始文件及其版本号。当然，如果您使用的是本世纪某个时间创建的系统，而不是最后一个系统，那应该不是问题。

Answer 4

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

我们的源代码管理系统还在每个文件的底部附加了签到注释。我最初讨厌更改日志，但随着时间的推移，我学会了喜欢它。合并更改时确实很有用。

Answer 5

最初在这里回答，但自从删除后：134249

我只会说两件事：

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

其他任何不必要的毛茸茸都是无法维持的，最终会变得比没有任何东西更糟糕。

当时我在一家大型国防公司工作，我们有严格的编码标准。如果你跟着他们去写信（大多数人没有），你的大部分标题都将主要由那些毫无意义的绒毛组成。更糟糕的是，需要将完全相同的绒毛放在源文件中，这意味着绒毛的两个副本已经过时并且会产生误导。

Answer 6

我曾经喜欢将版本控制关键字放在文件头中。但从那种痛苦中恢复过来。 :)有两个原因：

没有人提出任何有用的评论。你总是看着版本控制系统报告的差异。
在尝试区分大型文件集时会产生噩梦，因为关键字会产生差异，这是文件中唯一的区别。

Answer 7

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

我绝对不会反对嵌入检查邮件。那些非常有用。

Answer 8

如果您使用的是CVS，请查看keyword substitutions。它们将有助于自动嵌入该信息。

我个人认为这是我所有源文件的顶部：

// $Id$

我嵌入的其他信息性评论用doxygen解析，如果它们与特定的东西（文件，类，类型等）有关。

Answer 9

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

版权，

RCS文件名，

修改日期，

最后一次更改的作者，

RCS修订号

我觉得这很方便。我真的很喜欢在每个文件中自动填充文件名，因为它可以非常快速地搜索文件的解决方案。

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中设置一个宏来添加它并在我创建新文件时填写默认信息

Answer 11

我通常只在...时添加任何“评论信息” 我不认为我会记得或者不清楚什么是在做什么要么当我发布源代码时，我实际上希望其他人能够使用/从中学习。

Answer 12

我通常会在该文件中包含对代码目的的描述。其他一切似乎都在其他地方处理：源代码管理中的日期和注释等。

Answer 13

每个人都说你的源代码控制将拥有日期和程序员信息，但并非总是如此。我在一家使用Source Safe的商店工作过，直到有人决定将文件移到另一个位置才行。那时，根据SS，它基本上变成了一个新文件，并且以前没有历史记录。

也许正因为如此，程序员姓名和日期会自动添加到文件顶部的评论部分。如果必须有超过10个条目，我们将删除所有中间条目，只留下原始日期和作者，以及当前信息。

Answer 14

Answer 15

我们使用MSVC＆amp; VSS并有一个插件，可以在办理登机手续时将您指定的任何评论添加到作为评论签入的文件中。查看CPP文件的顶部以查找更改的错误跟踪票号是非常方便的。

Answer 16

我使用Subversion。这就是我想要接近顶部的内容。

$Id$
$HeadURL$

替换修订版，最后一个编辑器，然后替换存储库中文件的位置。虽然我总是使用工作副本，但这可以让我打印/通过电子邮件发送文件，稍后再查看它以确切知道它来自何处。 $HeadURL$ 特别好，因为它告诉文件所在的项目和分支以及如何到达它（对于较大的嵌套子包等很好）。

同意大手动注释块的无用 - 虽然建议使用docstrings / Javadoc - 并自动附加提交日志。

听起来有些人正在使用可怕的VCS，如果你得到关键字本身产生的差异或合并冲突。 Subversion handles it well.

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

16 个答案: