标准变更评论

Question

我正在寻找一些关于评论PHP变化的标准格式的方向。在与大量项目的各种开发人员合作时，评论不断发表，并且在大多数情况下，评论的评论很差或根本没有评论。

以下是一个示例，请随意展开：

/**
 * Author: [first and last name]
 * Date Changed: [YYYY-MM-DD]
 * Description: [description]
 */

问：有人知道评论PHP变化的标准方法吗？

Answer 1

此类内容不应放入文件注释。使用 revision control software 存储文件的所有版本（不仅仅是最新版本）。永远不要让开发人员没有它。此类软件允许您使用源代码执行更多：

• 您可以找到更改文件每一行的人
• 您可以将文件还原为以前（或正在运行）的版本
• 您可以创建源的不同分支并自动合并
• 您可以自动构建软件并自动运行测试
• 备份您的源存储库，您永远不会丢失您的工作
• ... and more

Answer 2

除了使用源代码控制之外，注释通常应该集中在源代码的当前状态，而不是提供详细的历史记录，除非是解释性上下文。

评论应该描述程序的 和 的原因，而不是管理暂存器或历史填写表单。这是一个工程师与另一个工程师沟通的方式 - 或者可能提醒自己 - 概念模型是什么。这可以解释实现的基础，例如其理念，预期用法或世界观。但是 - 众所周知 - 工程师不能成为职员。

我想我们都看到了这样的来源：

/*
 * Function:  (fill in name)
 *
 * Returns:  (fill in type)
 *
 * Date:  (current date)
 *
 * Revision (revision number)
 *
 * Author:  (your name or initials)
 *
 * Description:
 * (describe function)
 */

没有人填写任何但最无用的细节 - 如果有的话。