Question

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

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

Answer 1

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

/*
@(#)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 $值的值。我有一个shell脚本驱动Perl脚本来维护版权日期;我需要记住在任何给定年份我第一次编辑文件时使用它。我还没有打扰过制作一个过滤器脚本，这个脚本只是攻击了版权线（对我来说这是不寻常的 - 我制作了很多脚本）。该文件采用“未分发”格式;当我使用产品分发它时，'：PRODUCT：'meta-keyword被扩展为命名相关产品（通过我的发布构建软件）。显然，我的名字和文件的目的都不需要太多维护。（顺便说一句，我仍然更喜欢SCCS管理关键字的方式 - $ RCSfile $等的SCCS等价物。）

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

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

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

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

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

我不同意文件名不是值得保留在文件中的元数据的注释。我认为值得保留 - 因为当内容没有时，名称可以改变，如果元数据存在，更容易看到它来自何处。当然，恶意程序可以篡改（或删除）元数据 - 但它们通常不会。

Answer 2

一种选择是在Subversion服务器中放置一个预提交挂钩，用于检查标头是否存在。除了自我和团队纪律之外，没有什么可以确保它保持最新状态;你可以自动检查其中一些（例如Created，Modified by等），但你可以首先使用Subversion属性，其余的是判断调用。你怎么能自动更新文件的目的呢？

一般来说，我不是很喜欢这种事情。您已经知道文件的名称（duh），作者，修饰符，创建日期等：只需询问Subversion。将所有这些放在文件顶部最多浪费空间，最坏的情况可能是错误的。该文件的目的往往是有用的，但你必须确保更新，这更多的是编码风格的问题。

Answer 3

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

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

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

使用编辑器宏可以轻松实现插入。

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

3 个答案: