PHP：評論代碼

有理論上的問題。

我使用KohanaPHP框架創建一個簡單的應用程序，只是fyi。這是我第一次使用框架，並且有一個 - 對你們中的一些人可能是愚蠢的 - 問題。

在開發類或函數時，我使用DocBlock來紀念我的代碼。想知道如何在使用框架時評論我的代碼？我的意思是編碼代碼的一部分，而不是整個控制器。

基本上，我用下面的方法：

// Check if variable_name is greater than zero 
if($this->var > 0) { 
    // do something 
} else { 
    // do something 
} 

if($result) { 
    // display confirmation message 
} else { 
    // display errors 
}

我這樣做是正確的方法是什麼？在代碼中插入註釋是否有任何標準？

編輯：讓我解釋一下，我沒有使用像「檢查變量是否大於零」之類的註釋。我只是想知道將註釋放入代碼是否是一種好的做法。

問候，湯姆

來源

2010-08-11 Tom

如果「檢查，如果變量名是大於零」是註釋的一個真實的例子，你肯定做錯了。 – 2010-08-11 19:39:44

你可以下定決心你的問題是什麼？你原來的問題是問是否有任何標準（比特模糊）。然後你在編輯中說，你只是在問是否是評論你的代碼的好習慣......然後在對另一個答案的評論中你說'我也看到了不同的評論方法，但是我問的是否是正確的將這種評論放入代碼中，它明確要求*種類的評論...所以你想知道什麼？ – 2010-08-11 19:51:03

評論都是騙子！ 評論的問題在於，您必須在更新代碼時更新它們。如果你不這樣做，你會得到如下代碼：

// sum $a and $b 
$x = $a * $a - $b;

因此，記錄代碼的最好方法是讓它真正清楚！我會寫你這樣的代碼：

if (isPositive(3)) { 
    doA(); 
} else { 
    doB(); 
} 

if($result) { 
    displayConfirmationMsg(); 
} else { 
    displayErrors(); 
}

此代碼不需要評論，因爲在所有它是非常簡單的瞭解吧！

好了，反正當我必須寫評論（幾乎沒有），我去與//格式，但我認爲這並不重要。

順便說一句，看看叔叔的這真棒視頻鮑勃http://bit.ly/AYqFT

來源

2010-08-11 19:52:28 Alfwed

一些（如果不是大多數）PHP程序員使用註釋他們的代碼雙斜線法（//）。實際上沒有標準，我看到有人在線的開頭使用英鎊符號（#）發表評論，還有其他人用/*和*/註釋掉塊。

來源

2010-08-11 19:37:53 esqew

感謝您的評論。我也看到了不同的評論方式，但我是問，如果是正確的把那種註釋到代碼:) – Tom 2010-08-11 19:40:56

// Check if variable_name is greater than zero

這樣的評論毫無價值。我只知道很少的PHP，即使我對它一無所知，我可以立即告訴（或者至少，非常自信地猜測）看到這條線後。

作爲一般（語言無關）的經驗法則，編寫大多是自我記錄（通過使用描述性名稱，避免不明顯的快捷方式等）的代碼，並且只評論你爲什麼做一些看起來錯誤/奇怪的事情。

來源

2010-08-11 19:40:41 delnan

與註釋的視覺風格無關，但像「檢查變量名是否大於零」這樣的評論本身就是一個壞評論。它所做的就是複製下面一行中的信息。代碼應該包含變量，函數和其他可以讀取的名稱，以瞭解正在發生的事情。

除此之外，我沒有看到雙斜線註釋類型沒有錯。

來源

2010-08-11 19:40:57

個人而言，我很謹慎地內聯文檔（儘管我在宗教上將doc-blocks放在方法，類和成員變量中）。我相信代碼本身應該儘可能自我記錄。

有些時候你需要做一些不明顯的事情，甚至可能違反直覺。這是內嵌評論的時間。儘量不要解釋代碼塊的作用，但爲什麼它這樣做。

有一個在Phing的CodeCoverageReportTask類一個很好的例子：

// Strange PHP5 reflection bug, 
//  classes without parent class or implemented interfaces 
//  seem to start one line off 
if ($reflection->getParentClass() == NULL 
    && count($reflection->getInterfaces()) == 0) 
{ 
    unset($coverageInformation[$classStartLine + 1]); 
} 
else 
{ 
    unset($coverageInformation[$classStartLine]); 
}

而且又是個剛剛從幾行字下來：

// PHP5 reflection considers methods of a parent class to be part 
//  of a subclass, we don't 
if ($method->getDeclaringClass()->getName() != $reflection->getName()) 
{ 
    continue; 
}

來源

2010-08-11 19:44:16 ircmaxell

IMO意見不應該解釋的代碼沒有什麼，只是爲什麼（或其他事情絕對需要去了解它）。解釋代碼的作用是重複信息，應該始終避免。 – 2010-08-11 19:46:00

@Arve Systad：我也是這麼做的（當然，99.95％的時間）。我確實認爲有些時候你可能想要解釋如何（這就是爲什麼我加入OP）。但你的理由更好。我從我的回答中編輯了這種情緒...... – ircmaxell 2010-08-11 20:12:22

我完全同意，註釋不應該解釋代碼做什麼，只有爲什麼。但是，在代碼中加入必要的評論絕對是一種好的做法。當我回頭查看我的一些代碼（php或其他）時，我希望我更清楚地評論。

但是，隨着意見的唯一標準是一致！保持一致，你不必擔心如何混淆評論（僅限於何時使用它們）。

來源

2010-08-11 20:00:13 palswim

PHP：評論代碼

回答

相關問題