什么是在PHP5中评论的有效和可读的方法？

在过去的2个月里，我一直在学习PHP，我已经确定了两种以上用于评论代码的风格！我没有看到太多的一致性......我认为这通常意味着艺术家在工作。所以我想知道：有哪些有效的评论方法仍然可读/实用？在一个并排的地方看到所有有效的可能性将提供我正在寻找的改进评论的概述什么是在PHP5中评论的有效和可读的方法？

/* 
| This is what I now use (5chars/3lines) I name it star*wars 
\*

来源

2011-04-11 Sam

之前看过没有评论可读性的单个问题有没有一个编辑器突出显示您的评论？ – 2011-04-11 08:52:12

@Colonel yessir：* DreamWeaver *＆* Notepad2书签版*做颜色em。然而，写作评论的数量和风格使他们对我可读或不可。我猜想一个优秀的懒惰评论者首先想到的简短的必要评论比看起来更难。我有时甚至无法解读我自己的评论。这是正常的吗？ – Sam 2011-04-11 09:00:21

报价上评论的手册：

PHP支持 'C'，'C++和Unix Shell风格（Perl的风格）的意见。例如：

<?php 
    echo 'This is a test'; // This is a one-line c++ style comment 
    /* This is a multi line comment 
     yet another line of comment */ 
    echo 'This is yet another test'; 
    echo 'One Final Test'; # This is a one-line shell-style comment 
?>

一般情况下，你会想avoid using comments in your sourcecode。引用Martin Fowler：

当您觉得需要编写评论时，首先尝试重构代码，以便任何评论变得多余。

这意味着像

// check if date is in Summer period 
if ($date->after(DATE::SUMMER_START) && $date->before(DATE::SUMMER_END)) {

应该重写

if ($date->isInSummerPeriod()) { …

另一个意见类型，你会遇到，有时是分离的评论，例如像

// --------------------------------------------

或

################################################

那些通常表示，他们正在使用的代码是做得太多。如果你在课堂上发现了这个问题，请检查课程的责任，看看它的某些部分是否更好地重构为独立课程。

至于API文档，常用符号是PHPDoc，例如，

/** 
* Short Desc 
* 
* Long Desc 
* 
* @param type $name description 
* @return type  description 
*/ 
public function methodName($name) { …

我认为，你可以忽略短期和长期说明如果剩余方法的签名清楚地表达它做什么。然而，这需要在如何实际编写Clean Code方面有一定的纪律和知识。例如，以下是完全多余：

/** 
* Get the timestamp property 
* 
* The method returns the {@link $timestamp} property as an integer. 
* 
* @return integer the timestamp 
*/ 
public function getTimestamp() { …

，应当缩短到

/** 
* @return integer 
*/ 
public function getTimestamp() { …

不用说，无论你去为完整的API文档与否也取决于项目。我期望任何可以下载和使用的框架都有完整的API文档。重要的是，无论你决定做什么，始终如一地执行。

来源

2011-04-11 08:42:12 Gordon

'if（FALSE === $ date-> isInSummerPeriod（））'yoda style ftl。除此之外，当函数预期返回true时，使用'if（！func（））'...... – ThiefMaster 2011-04-11 08:56:26

'（FALSE === something）'本身是不可读的。我相信很好的Martin会用'if（$ date-> isInSummerPeriod（））'来写它，这个函数已经返回boolean，因此不需要进行严格的比较。 – 2011-04-11 08:58:17

双合欢，哈哈:)虽然避免评论的优秀点，在这个完全显着的答案宝石。 – 2011-04-11 08:59:59

您应该明确地使用phpdoc标准。这里是适合初学者的quick start。

我相信你已经看到的评论是这样的：

/** 
* example of basic @param usage 
* @param bool $baz 
* @return mixed 
*/ 
function function1($baz) 
{ 
    if ($baz) 
    { 
     $a = 5; 
    } else 
    { 
     $a = array(1,4); 
    } 
    return $a; 
}

谈到这种方式使得它不仅容易让大多数PHP开发人员阅读，但你也可以产生很好的单证。

来源

2011-04-11 08:23:49 alexn

......许多IDE也可以解析它们:)这使得代码完成成为一个强大的工具。 – KingCrunch 2011-04-11 08:45:59

使用phpdoc guidelines进行评论很常见。这包括用于生成文档的注释。

来源

2011-04-11 08:24:27 halfdan

对我来说，他们每个人看起来同样可读。
我正在使用单行和多行注释。

以灰色突出显示时，它们始终可见并与其他代码截然不同。
我在

来源

2011-04-11 08:54:16

什么是在PHP5中评论的有效和可读的方法？

回答

相关问题