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

Question

您认为值得在源代码文件开头的注释中添加哪些信息？

我能想到的只是作者的名字,也许是文件创建的日期(尽管我不确定这些信息是否有任何有用的价值).

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

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

Answer 1

放在文件头中的内容:

• 源代码所属的库/组件
• 版权详情
• 源文件中类(es)的简短而有意义的描述

什么不放在文件头中:

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

• 作者姓名.为什么？

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

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

Answer 2

• 版权
• 原作者
• 许可证(如果它是开源的)
• 单行目的陈述或描述
• 进一步的整体文档和使用示例

编辑:改变作者(S)到原始作者(S)