Coding style 格式化块注释

第一种格式似乎比第二种更受欢迎。为什么呢

---

第一个（每行星号）

第二个（星号的最小数量）

---

可能是因为它更可读，如果注释有很多行，即使看不到结尾，您也知道您正在阅读注释。

它（可以说）更可读或更好看。人们使用ASCII码艺术已有相当一段时间了

/*********************
 * here is the doc   *
 *********************/

---

或者别的什么。

更容易看到评论的开头和结尾

只需向下扫描左列，直到星号“用完”才能找到下一位代码

第一种方法出现故障的地方是重写注释的时候。现在需要重新设置行的格式，使星号对齐。这是一个禁忌，除非你有一个自动为你做这件事的工具

在麦康奈尔的《代码完成》（第二版）第790页中，他说：

对于较长的注释，创建双斜杠的长列、手动断开行与行之间的文本行以及类似活动的任务不是很有意义，因此/*…*/语法更适合于多行注释

关键是你应该注意你如何度过你的时间。如果您花费大量时间输入和删除[文本]以使[星号]对齐，则您不是在编程；你在浪费时间。找到一种更有效的风格

---

主要原因是PHP文档编制人员

诸如的文档管理器是为解析该形式的注释块而构建的，可解析注释块的示例如下：

/**
 * Page-Level DocBlock
 * @package MyPackage
 * @category mycategory
 */

正如您可以看到的，星号在每一行上，有些行包含一个

@

符号，这就是您所说的标记表示器，它告诉解析器应该处理这一行，并将其归档到文档的类别值下

---

另外，我们还将看到，这也表明，对于此类解析器和可读性，您应该使用这种类型的注释。

我喜欢它，因为它在视觉上区分了块注释代码和文档

如果我想注释掉一堆代码，如下所示：

/*
int i;
someCode(i);
print i;
*/

更好，因为我可以移动开始/结束部分以启用部分，或者删除两行以启用全部。用另一种格式我做不到。因此，文档最好采用另一种样式，因为您从未试图“取消注释”文档

现在，对于富编辑器，我更喜欢使用行注释注释代码，但这是另一个参数

已注释代码的在线注释

我更喜欢注释掉的代码：

//   int i;
//   someCode(i);
//   print i;

原因有很多。首先，它使一行很容易被取消注释（启用）。第二，它提供了一个更好的视觉指示，表明它被注释掉了，然后使用块注释（这依赖于语法突出显示，正如其他人所提到的）

但第三，也是最重要的一点，它允许您在注释内容中安全地包含块注释

当我注释出以下内容时，请注意SO语法突出显示的差异：

/**
 * Does something to i and then prints i
 */
public void messWithI() {
    int i;
    someCode(i);
    print i;
}

带块注释：

/*/**
 * Does something to i and then prints i
 */
public void messWithI() {
    int i;
    someCode(i);
    print i;
}*/

//   /**
//    * Does something to i and then prints i
//    */
//   public void messWithI() {
//       int i;
//       someCode(i);
//       print i;
//   } 

带行注释：

/*/**
 * Does something to i and then prints i
 */
public void messWithI() {
    int i;
    someCode(i);
    print i;
}*/

//   /**
//    * Does something to i and then prints i
//    */
//   public void messWithI() {
//       int i;
//       someCode(i);
//       print i;
//   } 

---

为此，您需要一个富编辑器的原因是，如果您以这种方式手动应用/删除注释，那么将需要大量的按键。IDE有一些实用程序可以为您实现这一点（Eclipse是CTRL-/），高级文本编辑器有宏或至少是垂直选择。

我个人对每个注释都使用

/

，并保留

/***/

作为临时用途，例如在重构时注释掉许多函数。对块注释使用

/**/

将阻止我快速注释大量代码

因此，我的区块注释如下所示：

//*****************************
//  Some 
//  Comments
//  Here
//*****************************

---

现在将注释改为“这是多用途文档”，看看需要多大的努力。我能想到的最糟糕的注释样式-至少80个字符宽-但即使这样也会失败，因为插入注释意味着必须在每行末尾加空格键（不要尝试制表符，我们都知道结果如何）都是真的，但它仍然存在。也许这是一种拖延。对于IDE（或任何具有语法突出显示功能的优秀编辑器），这真的是一个问题吗？对我来说，我必须说，这一切都是一样的。我只是回答了我认为可能是人们的原因。RobertPitt有一个更好的理由。也许这是特定于语言的实践，因为除了JavaDoc，我还没有见过这种风格。Eclipse（可能还有其他IDE）会自动做到这一点。这是PHP和ActionScript中的常见做法。@Carlos:不总是这样。如果使用CTRL-SHIFT-/则不会。它对注释块使用这种样式。这绝对是特定于语言的。在C#中，我们只需对块注释中的每一行使用

/

，如果是XML注释，则使用

/

。这些都不适用于PHP，我认为这可能是PHP的主要原因。如果说这就是为什么大多数Java风格（例如）都使用这种形式，那么考虑到大多数Java开发人员并不是第一个PHP开发人员，那么这就有点假设了。这是一个很好的答案。我对你的最后一句话很好奇。为什么您更喜欢富编辑器中的行注释？您提出了一个很好的观点。再次感谢你的回答。我希望我能投更多的票。