在 C++ 中自动更新标题注释答案

【问题标题】：Auto updated header comments in C++在 C++ 中自动更新标题注释
【发布时间】：2010-11-13 14:17:52
【问题描述】：

这是我在 WxWidgets 中找到的标题之一，我喜欢它。我想知道是否有办法在我的所有源文件中插入这样的标题并保持它自动更新？它包括我知道的 SVN 的两个属性。

/////////////////////////////////////////////////////////////////////////////
// Name:        <filename>.cpp
// Purpose:     
// Author:      <AuthorName>
// Modified by:
// Created:     $Date$
// RCS-ID:      $Id$
// Copyright:   (c) <Year> <AuthorName>
// Licence:     <licensetype>
/////////////////////////////////////////////////////////////////////////////

【问题讨论】：

“自动更新”是什么意思？ SVN 会自动将这些属性替换为它们的实际值。
一般来说，请详细说明您要执行的操作。将此标头添加到项目中所有现有的 .h 和 .cpp 文件中？配置您的 IDE 以便它自动在所有新文件中插入标头？如果是后者，你的 IDE 是什么？
我用的是VS 2008。我的意思是在我把它插入到所有文件之后，我可以自动更新一些字段。例如，更改变量，然后它会在所有文件中自动更新。

标签： c++ header comments

【解决方案1】：

我相信几乎所有这些字段都是完全多余的，并且对文件的描述性没有任何价值：

文件名可能仅在从磁盘崩溃恢复期间有用？预处理器会在有用时自动包含它（例如，如果您试图找到一个讨厌的标头错误）。
.cpp 文件的目的几乎总是包含一个或多个包含一个或多个类声明的 .h 文件的实现。描述每个类目的的注释最好放在类声明之前的头文件中，如果类的接口发生变化，它也更有可能被更新。
一旦第三方进行了单行更改，作者字段将永远不会准确；改用版本控制系统的 log / annotate / blame 命令以可靠的方式跟踪它。
“修改者”、“创建者”和“RCS-ID”同样无用且容易过时。 RCS-ID 只能识别文件在最后一次提交时的版本，它不能解释此后所做的任何未版本化的更改。相反，如果您关心文件的确切版本，请改用 MD5 总和之类的强大功能。

/* Copyright 2009, Your Company Name. All right reserved. */

使用编辑器宏可以很容易地插入它。

【讨论】：

我怀疑像最初作者这样的信息一文不值。我什至看到源文件一开始就维护良好的更改/作者历史，这是非常值得的。根据我的经验，几乎没有开发人员会检查 VCS 中的历史记录。并且没有任何 vcs 的项目仍然不是那么少。

【解决方案2】：

这部分取决于您使用的 VCS。对于我自己的工作，我在 1999 年之前一直使用 SCCS，但为了避免 Y2K 出现问题，我改用了 RCS（SCCS 日期格式使用 2 位数字表示年份，我认为这是不可接受的）。因此，我对如何合理合理地使用这些系统有强烈的看法。在某处，我已经讨论了文件头中的内容，但是找到插图比其他答案更简单......

/*
@(#)File:           $RCSfile: stderr.c,v $
@(#)Version:        $Revision: 9.14 $
@(#)Last changed:   $Date: 2009/07/17 19:00:58 $
@(#)Purpose:        Error reporting routines
@(#)Author:         J Leffler
@(#)Copyright:      (C) JLSS 1988-91,1996-99,2001,2003,2005-09
@(#)Product:        :PRODUCT:
*/

这是我最古老的源文件之一 - 从 SCCS 迁移到 RCS。 VCS（即 RCS）自动维护 $RCSfile$、$Revision$ 和 $Date$ 的值。我有一个驱动 Perl 脚本来维护版权日期的 shell 脚本；我需要记住在任何给定年份第一次编辑文件时使用它。我还没有费心制作一个仅仅破解版权行的过滤器脚本（这对我来说有点不寻常 - 我制作了很多脚本）。该文件采用“未分发”格式；当我将它与产品一起分发时，':PRODUCT:' 元关键字被扩展以命名相关产品（通过我的发布构建软件）。显然，我的名字和文件的目的都不需要太多维护。（顺便说一句，我仍然更喜欢 SCCS 管理关键字的方式 - SCCS 等价于 $RCSfile$ 等）

在版本控制系统本身不支持关键字的情况下，决定如何处理这些信息要困难得多。第一条规则是“不要与你的 VCS 对抗”。战争故事 - 我们尝试与 VCS 作战，但没有成功。很久以前（15 年前），公司从 SCCS 切换到 Atria Clearcase（现在的 IBM Rational ClearCase）。 ClearCase 不支持将版本信息嵌入到源文件中。它确实支持签入触发器。我们编写并部署了一个触发器，以确保将 ClearCase 版本号嵌入到文件中，就像之前的 SCCS 版本号一样。签入触发器工作正常；我们可以在视图内部或外部查看文件，并查看它属于哪个版本。但是版本号的更改破坏了合并代码 - 所有合并都变成了手动合并，即使唯一的冲突是版本号。这是因为我们正在与 VCS 作战，它不愿意让我们获胜。所以，我们最终放弃了签入触发器。

我仍在尝试研究如何使用现代 DVCS（如 git）处理版本标记源文件。看起来我将不得不重新设计我的整个发布系统——可能作为一个涵盖 SCCS 和 RCS 的混合体（就像现在一样，尽管 SCCS 部分已经有十年的大部分时间没有使用过）以及 git。

许多人使用的一个理论是，您应该避免将元数据构建到源文件中。我仍然完全相信这很好 - 我认为即使源文件脱离其原始上下文（已重命名，从其原始包中删除，修改并包含在某些新产品）。在使用 DVCS 时，我可能还不得不接受这种观点。

我的理论（我使用但不一定被其他人使用）是元数据应该在文件中，因为它们并不总是在其原始上下文中使用，并且元数据可以存活并帮助识别其来源，即使是几十年后。因此，当我构建源代码发布时，我使用我的发布软件自动编辑产品信息，使用 :PRODUCT: 等符号来标记应该编辑的内容。如果您下载我贡献给IIUG（国际Informix 用户组）网站的任何包，您可以在工作中看到这一点。我推荐 SQLCMD 作为可能是最大和最新的软件包——尽管它从 90 年代中期和 23 版左右就已经可用了（目前在 86.00 版上）。

我在使用 git 时遇到的最大问题之一是我的几乎所有程序都使用 stderr.c 和 stderr.h 中的代码。但是，我还不清楚如何在使用它的许多产品中合并相同的代码，而无需对其进行多次维护。这远不是我在许多不同产品中使用的唯一一对源文件。但是我不想为每个产品构建整个库 - 库会比许多产品大，并且任何给定的产品只使用库中的一些文件。 ...啊，总有一天，启蒙会到来...

我不同意 cmets 的意见，即文件名不是值得保留在文件中的元数据。我认为值得保留 - 因为名称可以在内容不更改时更改，并且如果元数据存在则更容易查看它的来源。当然，恶意软件可以篡改（或删除）元数据 - 但他们通常不会。

【讨论】：

【解决方案3】：

一种选择是在您的 Subversion 服务器中放置一个预提交挂钩，以检查标头是否存在。但是，除了自我和团队纪律之外，您实际上无法做任何事情来确保它保持最新状态；您可以自动检查其中的一些（例如，创建者、修改者等），但您可以首先使用 Subversion 属性，其余的都是判断调用。如何自动更新文件的用途？

不过，总的来说，我不太喜欢这种事情。您已经知道文件的名称 (duh)、作者、修改器、创建日期等：只需询问 Subversion。将所有这些放在文件的顶部最多会浪费空间，最坏的情况可能是错误的。该文件的用途往往很有用，但您必须确保对其进行更新，这更像是编码风格的问题。

【讨论】：

我坚持同样的理念，但是对于商业代码中的此类 cmets 有一个很好的论据（即，版本控制系统不一定被所有人使用，无论最佳实践可能是什么)，或者当代码通过电子邮件共享时，在文件中包含 cmets 可能会很有用。
我不喜欢版本控制更新字段的另一个原因是它会产生虚假的差异——即唯一的区别是日期字段。试图在大文件集中找到真正的差异会造成严重破坏。价值有限的东西一开始就不值得。