如何评论出包含PHP的HTML代码？

Question

我有一个包含PHP的HTML代码,我想对它进行全面评论.

<input type="hidden" name="returnurl" value="<?php if (!empty($link)) {echo $link;}?>">

如何在不单独评论的情况下注释HTML和PHP？

Answer 1

感谢Ross Patterson,我发现我完全误解了这个问题.所以这是新答案.我保留下面的旧答案,因为它可能对某些人有用.

新答案

你的情况很简单,因为你的代码中既没有PHP字符串也没有注释.这意味着对这段特定代码进行注释非常简单:

<?php
/*
<input type="hidden" name="returnurl" value="<?php if (!empty($link)) {echo $link;}?>">
*/
?>

问题是你迟早会发现自己处于不起作用的情况,因为评论的代码包含自己的注释.想象一下以下代码:

<div>
  You're logged in.
  <?php
  /**
   * Says "hello" to the person.
   * @param string $name The name of the person.
   */
  function SayHello($name)
  {
    echo 'Hello, ' . $name;
  }

  SayHello($personName);
  ?>
</div>

您不可能将其嵌入到单个注释中,因为它将在第7行中断开.

相反,您可以使用NOWDOC语法将代码嵌入到字符串中,并且永远不会使用此字符串:

<?php
$GUID2328f09280b94c22867d831a885b57eb = <<<'GUID2328f09280b94c22867d831a885b57eb'
<div>
  You're logged in.
  <?php
  /**
   * Says "hello" to the person.
   * @param string $name The name of the person.
   */
  function SayHello($name)
  {
    echo 'Hello, ' . $name;
  }

  SayHello($personName);
  ?>
</div>
GUID2328f09280b94c22867d831a885b57eb
?>

几点评论:

• 为什么我使用NOWDOC而不是简单的字符串？

  一个简单的字符串将在第5行断开(在"说"你好"").单引号字符串将在第2行(在"你是"上)中断.

• 为什么我使用NOWDOC代替HEREDOC？

  因为我不希望解析变量名.在这样的上下文中解析变量会导致很难找到和调试的问题,因为范围会发生变化.

• 什么是可怕的GUID2328 ......？

  我使用GUID来确保首先,字符串永远不会在实际结束之前终止,其次,字符串变量将永远不会在代码中后来合理使用.我输入了GUID前缀,因为HEREDOC/NOWDOC要求名称以字母开头,而不是数字.

  如果你发现它丑陋而愚蠢,请随意使用你想要的任何语法.

• 它会影响Web应用程序的性能,对吧？

  不要过早优化.初始化一个字符串可能会有性能成本,但它要么小到可以关心,要么甚至PHP解释器都足够聪明以优化代码并删除未使用的字符串(我非常怀疑).

请注意,您不应该首先评论大块代码.如果您不需要代码,只需将其删除即可.如果您认为以后可能需要它,请让版本控制处理它(您正在使用版本控制,是吗？).

老答案

你在评论谁？

• 开发商？然后用PHP评论.例:

  <?php /** The value is hidden for the moment to be backwards compatible, but the field
          * would be removed in the near future, since having this field presents a
          * security risk. See bug report 1422, http://example.com/bugs/1422 */ ?>
  <input type="hidden" name="returnurl" value="<?php if (!empty($link)) {echo $link;}?>">
  

  请记住,HTML评论是公开显示的.在上面的示例中添加评论是对黑客的礼物.

• 用户？然后用HTML评论.例:

  <!-- If `returnurl` is null or empty, the client would be redirected to the home page
       of the website. -->
  <input type="hidden" name="returnurl" value="<?php if (!empty($link)) {echo $link;}?>">
  

  在这里,目的是告诉用户有用的东西,例如屏幕废弃你的网站或做一些操纵HTML的东西(唯一有效的例子我会看到做一个真正的API对你来说太贵了,所以你是授权和邀请用户直接解析HTML代码).

请记住:

1. 每个人都可以看到HTML评论,

2. HTML注释被发送到客户端,增加了带宽的使用.注意:在大多数情况下,你不在乎; 除非您在Google主页上工作,否则这不会影响您网站的性能.

Answer 2

如果您用很少或没有 HTML 来注释 php 块，请使用 php 注释；如果您用很少的 PHP 来注释大块 HTML，请使用 HTML 注释。

将注释放在最清晰、最具描述性的任何地方并采用任何形式，并尝试在整个编码过程中保持一致的风格。

您还应该根据您实际评论的内容进行区分。如果您要对 HTML 结构进行注释，请使用 HTML 如果您要对 php 的详细信息进行注释，除非它是 HTML 块中间的一行，否则请使用 php.ini。注释风格应该与代码风格相辅相成。