问题标签 [comment-conventions]

我需要使用 HTML 注释来存储特定数据，但我不想使用由Dreamweaver <!-- #BeginLibraryItem "/File.lbi" -->或Frontpage等程序生成的已经存在的注释方案。

我怎么知道哪种评论方案问题最少，或者至少看起来不像其他现有的评论约定？

PS：有人告诉我评论中的双连字符“--”有时会破坏渲染。

有时评论时必须参考另一种方法。这是PHP中的一些示例：

那么如果bar类中有一个非静态方法B呢？在评论中命名其他方法的最佳方式是什么？

编辑

PHP 手册似乎mysqli->affected_rows与PDO::beginTransaction. 但它不包含方法名称后的括号。这里的利弊是什么？我的意思是很明显，一个方法后面跟着括号，那么为什么不把它们排除在外呢？

提前谢谢！

我正在寻找相当短但相当复杂的代码段（对象、函数、类、一组特定的变量名等）的示例，它们可以达到完美的禅意，就像自我文档和实现优雅的平衡一样。

它可能是您真正引以为豪的事情，也可能是您遇到并经历过“啊哈！”的事情。顿悟的时刻。

一些潜在标准（并非所有标准都需要在一个示例中满足）：

• 稀疏而集中
• 不言自明。也许写得这么清楚，即使是非程序员也能理解你想要做什么，即使他们不理解语法或实现细节。
• 明显有用（有多个用例，例如排序算法、方便的递归方法等）
• 聪明的
• 启蒙
• 生产质量和功能（例如不是伪代码）

我正在寻找一个示例片段，然后是对代码特别之处的简短评论。当然，最好的示例将需要最少的额外评论，因为它们有据可查。

版主注意：我是stackoverflow的新手，所以如果这个问题不合适或必须关闭，你能解释一下它在哪里违反了stackoverflow的规范吗？我不打算浪费人们的时间。

这个问题的目标是通过社区提供和评价的示例来学习良好的评论实践。

在写评论时，我有时会发现自己需要在写评论时用复数形式来谈论一个类型（类、结构等），例如：

问题是，类型名称是单数（即，Thing），但我想在评论中以复数形式讨论它们。

如果我说Things，它向读者表明它正在谈论一种称为 的类型Things，但事实并非如此。如果我说Thing's，它看起来很尴尬，因为它在语法上不正确（它要么是所有格要么是“Thing is”，而不是复数）。我可以谈论这个问题并说a list of Thing items

在编写复数类型时要遵守什么好的约定？

首先，我知道这个问题： 代码中的注释是否有标准格式？

但它没有回答我的问题。每当我编写代码时，我总是试图养成确保注释全部一致的习惯，但这就是我有时对我的代码格式约定优柔寡断的地方。特别是因为我希望我的代码是 80 左右行宽。

不用说，代码格式约定应该是：

• 易于阅读
• 易于修改

并且代码的不同部分可能有不同的注释格式，因此确保它们保持一致和可读是很重要的。

这里有些例子：

单线

多线

我有一个批处理文件，它运行几个执行表修改的 python 脚本。

1. 我想让用户注释掉他们不想运行的 1-2 个 python 脚本，而不是从批处理文件中删除它们（所以下一个用户知道这些脚本作为选项存在！）

2. 我还想添加注释以特别提醒他们在运行批处理文件之前需要在批处理文件中更新的变量。我看到我可以使用REM. 但它看起来更像是在用户运行后更新用户的进度。

是否有更恰当地添加评论的语法？

你们如何评论/记录您的 .sql 文件？是否有类似于 javadoc 之类的约定？在 facebook、twitter、google 等大型数据库密集型应用程序中通常会执行什么操作......