在源代码文件顶部的注释中放入哪些信息？

Question

您认为有哪些信息可以放在源代码文件开头的注释中？

我能想到的只是作者的名字，也许是文件的创建日期（虽然我不确定这些信息是否有任何有用的价值）。

[编辑] 为了澄清，我不是指在课前的评论，而是在文件的第一行，包括语句之前和其他什么。像

/**
 * Author:    Name
 * Created:   11.05.2009
 * 
 * (c) Copyright by Blub Corp.
 **/

Answer 1

放入文件头中的内容：

• 库/组件，源代码是
的一部分
• 版权详情
• 源文件
中类的简短且有意义的描述

什么不放在文件头中：

• 任何复制作为代码本身一部分的低级逻辑的东西。如果在源代码更改时未更新，则可能导致维护问题。

• 作者姓名。为什么呢？

  • 在修订控制系统的世界中，虽然某些代码可能是最初的作者，但最终所有权变得模糊。当代码进入生命周期的维护阶段，业主可以定期更换时，尤其如此。
  • 所有代码在经过足够的更改后最终成为“社区维基”; - ）
  • 您是否希望您的名字永远与所有代码相关联，并且知道您在代码死亡之前不会对代码负责？

• 创建和上次更改日期。这与上面列出的类似原因。修订控制包括这些信息 - 为什么要在标题中复制它，为自己做更多工作，并且当事情不可避免地发生变化时，有可能在评论中留下不准确的信息？

Answer 2

• 版权
• 原作者
• 许可证（如果是开源的）
• 单行目的陈述或说明
• 更多整体文档和用法示例

编辑：将作者更改为原作者

Answer 3

如果文件将包含一些非常常见的类/功能，可以用合理的常识来理解，那么如果源代码文件是非常特定的类/函数，那么你真的不需要在描述中加入太多内容。该项目或包含一个复杂的逻辑，那么你应该给出一个高水平的概述＆amp;源代码文件的目的。

Answer 4

文件编码！ （UTF-8）

# -*- encoding: utf-8 -*-

特别是如果您计划在某个时间点与世界其他地方的其他人分享您的代码。

Answer 5

以上所有内容也列出了该文件中代码目的的详细信息，您也认为这有助于调试和理解功能。这有助于维护和支持。