什麼是在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中評論的有效和可讀的方法？

回答

相關問題