PHP编程的五个良好习惯

dn001 2009-06-04 00:32:40

为代码添加注释

要为代码添加良好的注释有时似乎和编写代码一样难。要了解应该为哪些内容添加注释并不容易，因为我们常常倾向于注释代码当前做的事情。注释代码的目的是不错的主意。在函数的不是很明显的头部代码块中，告诉读者方法的输入和输出，以及方法的最初目标。

注释代码当前做什么是很常见的，但这是不必要的。如果代码很复杂，不得不注释它当前在做什么，这将暗示您应该重写代码，让它更容易理解。学会使用良好的名称和更短的方法，在不提供注释说明其用途的情况下提高代码的可读性。

不良习惯：函数注释过多或不足

清单 5 中的注释仅告诉读者代码在做什么 — 它正在通过一个循环进行迭代或添加一个数字。但它忽略了它为什么做当前的工作。这使维护该代码的人员不知道是否可以安全地更改代码（不引入新缺陷）。

清单 5. 不良习惯：函数注释过多或不足

＜?php

class ResultMessage 
{
    private $severity;
    private $message;
    
    public function __construct($sev, $msg) 
    {
        $this-＞severity = $sev;
        $this-＞message = $msg;
    }
    
    public function getSeverity()
    {
        return $this-＞severity;
    }
    
    public function setSeverity($severity)
    {
        $this-＞severity = $severity;
    }
    
    public function getMessage()
    {
        return $this-＞message;
    }
    
    public function setMessage($msg)
    {
        $this-＞message = $msg;
    }
}

function cntMsgs($messages)
{
    $n = 0;
    /* iterate through the messages... */
    foreach($messages as $m) {
        if ($m-＞getSeverity() == 'Error') {
            $n++; // add one to the result;
        }
    }
    return $n;
}

$messages = array(new ResultMessage("Error", "This is an error!"),
    new ResultMessage("Warning", "This is a warning!"),
    new ResultMessage("Error", "This is another error!"));
    
$errs = cntMsgs($messages);

echo("There are " . $errs . " errors in the result.n");

?＞

良好习惯：带注释的函数和类

清单 6 中的注释告诉读者类和方法的目的。该注释解释了为什么代码在做当前的工作，这对未来维护代码十分有用。可能需要根据条件变更而修改代码，如果能够轻松了解代码的目的，则修改起来很容易。

清单 6. 良好习惯：带注释的函数和类

＜?php
/**
 * The ResultMessage class holds a message that can be returned
 * as a result of a process. The message has a severity and
 * message.
 * 
 * @author nagood
 *
 */
class ResultMessage 
{
    private $severity;
    private $message;
    
    /**
     * Constructor for the ResultMessage that allows you to assign
     * severity and message.
     * @param $sev See {@link getSeverity()}
     * @param $msg
     * @return unknown_type
     */
    public function __construct($sev, $msg) 
    {
        $this-＞severity = $sev;
        $this-＞message = $msg;
    }
    
    /**
     * Returns the severity of the message. Should be one
     * "Information", "Warning", or "Error".
     * @return string Message severity
     */
    public function getSeverity()
    {
        return $this-＞severity;
    }
    
    /**
     * Sets the severity of the message
     * @param $severity
     * @return void
     */
    public function setSeverity($severity)
    {
        $this-＞severity = $severity;
    }
    
    public function getMessage()
    {
        return $this-＞message;
    }
    
    public function setMessage($msg)
    {
        $this-＞message = $msg;
    }
}


/*
 * Counts the messages with the given severity in the array
 * of messages.
 * 
 * @param $messages An array of ResultMessage
 * @return int Count of messages with a severity of "Error"
 */
function countErrors($messages)
{
    $matchingCount = 0;
    foreach($messages as $m) {
        if ($m-＞getSeverity() == "Error") {
            $matchingCount++;
        }
    }
    return $matchingCount;
}

$messages = array(new ResultMessage("Error", "This is an error!"),
    new ResultMessage("Warning", "This is a warning!"),
    new ResultMessage("Error", "This is another error!"));
    
$errs = countErrors($messages);

echo("There are " . $errs . " errors in the result.n");

?＞

标签：编程