什么是有效&可读的方法评论在PHP5？ [英] What are The Valid & Readable approaches to Commenting in PHP5?

问题描述

在过去的2个月里，我一直在学习PHP，我已经确定了两个以上的样式，人们用来评论代码！我没有看到太多的一致性...我认为通常意味着艺术家在工作。所以我想知道：什么是有效的方式来评论，仍然可读/实用？

In the past 2 months that I have been learning PHP, I have identified more than two styles people use to comment code! I haven't seen much consistency... which I think usually means artists at work. So I wondered: what are the valid ways to comment which are still readable/practical? Seeing all the valid possibilities in 1 place side by side will provide the overview that I am looking for to improve commenting

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

推荐答案

引用手册的注释：

PHP支持'C'，'C ++'和Unix shell风格（Perl风格）评论。例如：

PHP supports 'C', 'C++' and Unix shell-style (Perl style) comments. For example:

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

In general, you will want to avoid using comments in your sourcecode. To quote Martin Fowler:

当你觉得需要写评论时，首先要重构代码，使任何注释变得多余。

When you feel the need to write a comment, first try to refactor the code so that any comment becomes superfluous.

这意味着像

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

应重写为

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

有时遇到的是分隔符注释，例如

Another comment type you will sometimes encounter is the separator comment, e.g. something like

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

或

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

这些通常表示他们使用的代码是做太多。如果你在类中找到这个，检查类的责任，看看它的一些部分是否更好的重构到一个独立的类。

Those are usually indicative that the code they are used in is doing too much. If you find this in a class, check the responsibility of the class and see if some parts of it are better refactored into a standalone class.

对于API文档，常见符号是 PHPDoc ，例如

As for API docs, the common notation is PHPDoc, e.g.

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

我认为，如果剩余的方法签名清楚地沟通它做什么，你可以省略Short和Long Desc。但是，这需要一定的学科和知识，如何实际写入清洁代码。例如，以下是完全多余的：

I would argue that you can omit Short and Long Desc if the remaining method signature clearly communicates what it does. However, that requires a certain discipline and knowledge in how to actually write Clean Code. For instance, the following is totally superfluous:

/**
 * 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文档。重要的是，无论你决定做什么，都要持之以恒。

Needless to say, whether you go for full API docs or not also depends on the project. I'd expect any framework I can download and use to have full API docs. The important thing is just that whatever you decide to do, do it consistently.

这篇关于什么是有效&可读的方法评论在PHP5？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！