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

Question

在过去的两个月里,我一直在学习PHP,我发现有两种以上的样式用来评论代码!我没有看到太多的一致性......我认为这通常意味着工作中的艺术家.所以我想知道:评论的有效方法是什么仍然可读/实用？并排查看1个地方的所有有效可能性将提供我正在寻求改进评论的概述

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

Answer 1

引用评论手册:

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
?>

通常,您需要避免在源代码中使用注释.引用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) { …

我认为如果剩下的方法签名清楚地传达它的作用,你可以省略短篇和长篇.但是,这需要一定的纪律和知识,如何实际编写清洁代码.例如,以下内容完全是多余的:

/**
 * 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文档.重要的是,无论你决定做什么,都要始终如一地做到.