PHP Document 註釋標記及規範 && PHP命名規範

註釋標記

@access

• 使用範圍：class,function,var,define,module
• 該標記用於指明關鍵字的存取權限：private、public或proteced

@author

• 指明做者

@copyright

• 使用範圍：class，function，var，define，module，use
• 指明版權信息

@deprecated

• 使用範圍：class，function，var，define，module，constent，global，include
• 指明不用或者廢棄的關鍵字

@example

• 該標記用於解析一段文件內容，並將他們高亮顯示。Phpdoc會試圖從該標記給的文件路徑中讀取文件內容

@const

• 使用範圍：define
• 用來指明php中define的常量

@final

• 使用範圍：class,function,var
• 指明關鍵字是一個最終的類、方法、屬性，禁止派生、修改。

@filesource

• 和example相似，只不過該標記將直接讀取當前解析的php文件的內容並顯示。

@global

• 指明在此函數中引用的全局變量

@ingore

• 用於在文檔中忽略指定的關鍵字

@license

• 至關於html標籤中的<a>,首先是URL，接着是要顯示的內容
• 例如<a href=」http://www.baidu.com」>百度</a>
• 能夠寫做 @license http://www.baidu.com 百度

@link

• 相似於license
• 但還能夠經過link指到文檔中的任何一個關鍵字

@name

• 爲關鍵字指定一個別名。

@package

• 使用範圍：頁面級別的-> define，function，include
• 類級別的->class，var，methods
• 用於邏輯上將一個或幾個關鍵字分到一組。

@abstrcut

• 說明當前類是一個抽象類

@param

• 指明一個函數的參數

@return

• 指明一個方法或函數的返回指

@static

• 指明關建字是靜態的。

@var

• 指明變量類型

@version

• 指明版本信息

@todo

• 指明應該改進或沒有實現的地方

@throws

• 指明此函數可能拋出的錯誤異常,極其發生的狀況
• 普通的文檔標記標記必須在每行的開頭以@標記，除此以外，還有一種標記叫作inline tag,用{@}表示，具體包括如下幾種：

{@link}

• 用法同@link

{@source}

• 顯示一段函數或方法的內容

註釋規範

a.註釋必須是

/**
 * 註釋內容
 */

的形式

b.對於引用了全局變量的函數，必須使用glboal標記。

c.對於變量，必須用var標記其類型（int,string,bool…）

d.函數必須經過param和return標記指明其參數和返回值

e.對於出現兩次或兩次以上的關鍵字，要經過ingore忽略掉多餘的，只保留一個便可

f.調用了其餘函數或類的地方，要使用link或其餘標記連接到相應的部分，便於文檔的閱讀。

g.必要的地方使用非文檔性註釋，提升代碼易讀性。

h.描述性內容儘可能簡明扼要，儘量使用短語而非句子。

i.全局變量，靜態變量和常量必須用相應標記說明

示例

<?php
/**
 * Sample File 2, phpDocumentor Quickstart
 *
 * This file demonstrates the rich information that can be included in
 * in-code documentation through DocBlocks and tags.
 * @author Greg Beaver <cellog@php.net>
 * @version 1.0
 * @package sample
 */

//PHP code

/**
 * A sample function docblock
 * @global string document the fact that this function uses $_myvar
 * @staticvar integer $staticvar this is actually what is returned
 * @param string $param1 name to declare
 * @param string $param2 value of the name
 * @return integer
 */
function firstFunc($param1, $param2 = 'optional') {
    static $staticvar = 7;
    global $_myvar;
    return $staticvar;
}
?>

phpDocumentor官方網站

 

---

 

YII框架的註釋範例：

/**
 * CHttpSession提供了session級的數據管理和相關配置
 *
 * 開啓session 調用 {@link open()};
 * 完成和發送session數據，調用 {@link close()};
 * 清除session,調用{@link destroy()}.
 *
 *
 * CHttpSession can be used like an array to set and get session data. For example,
 * <pre>
 *   $session=new CHttpSession;
 *   $session->open();
 *   $value1=$session['name1'];  // get session variable 'name1'
 *   $value2=$session['name2'];  // get session variable 'name2'
 *   foreach($session as $name=>$value) // traverse all session variables
 *   $session['name3']=$value3;  // set session variable 'name3'
 * </pre>
 *
 * The following configurations are available for session:
 * <ul>
 * <li>{@link setSessionID sessionID};</li>
 * <li>{@link setSessionName sessionName};</li>
 * <li>{@link autoStart};</li>
 * <li>{@link setSavePath savePath};</li>
 * <li>{@link setCookieParams cookieParams};</li>
 * <li>{@link setGCProbability gcProbability};</li>
 * <li>{@link setCookieMode cookieMode};</li>
 * <li>{@link setUseTransparentSessionID useTransparentSessionID};</li>
 * <li>{@link setTimeout timeout}.</li>
 * </ul>
 * See the corresponding setter and getter documentation for more information.
 * Note, these properties must be set before the session is started.
 *
 * CHttpSession can be extended to support customized session storage.
 * Override {@link openSession}, {@link closeSession}, {@link readSession},
 * {@link writeSession}, {@link destroySession} and {@link gcSession}
 * and set {@link useCustomStorage} to true.
 * Then, the session data will be stored and retrieved using the above methods.
 *
 * CHttpSession is a Web application component that can be accessed via
 * {@link CWebApplication::getSession()}.
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @version $Id: CHttpSession.php 2497 2010-09-23 13:28:52Z mdomba $
 * @package system.web
 * @since 1.0
 */
class CHttpSession implements IteratorAggregate, ArrayAccess, Countable {

    /**
     * @var boolean whether the session should be automatically started when the session application component is initialized, defaults to true.
     */
    public $autoStart = true;
    private static $_instance = NULL;
 
    /**
     * Initializes the application component.
     * This method is required by IApplicationComponent and is invoked by application.
     */
    public function init() {
        if ($this->autoStart) {
            $this->open();
        }

        
        register_shutdown_function(array($this, 'close'));
    }

    /**
     * Returns a value indicating whether to use custom session storage.
     * This method should be overriden to return true if custom session storage handler should be used.
     * If returning true, make sure the methods {@link openSession}, {@link closeSession}, {@link readSession},
     * {@link writeSession}, {@link destroySession}, and {@link gcSession} are overridden in child
     * class, because they will be used as the callback handlers.
     * The default implementation always return false.
     * @return boolean whether to use custom storage.
     */
    public function getUseCustomStorage() {
        return false;
    }

    /**
     * Session open handler.
     * This method should be overridden if {@link useCustomStorage} is set true.
     * Do not call this method directly.
     * @param string $savePath session save path
     * @param string $sessionName session name
     * @return boolean whether session is opened successfully
     */
    public function openSession($savePath, $sessionName) {
        return true;
    }

	// 截取了一部分
 
}

 

 

---

 

 

PHP命名規範

先了解下

一、什麼是 駝峯命名法？  百度百科   

二、大駝峯 與 小駝峯 的區別 ？   百度百科    

1.類名：大駝峯命名法

2.類屬性：

public、protected類型的，小駝峯命名法；

private類型的，下劃線（_）開頭，小駝峯命名法；

3.類方法：

public、protected類型的，小駝峯命名法；

private類型的，下劃線（_）開頭，小駝峯命名法；

4.類方法參數：小駝峯命名法；

5.函數：採用C GNU的慣例，全部的字母使用小寫字母，使用下劃線（_）分割單詞；

6.函數參數：小駝峯命名法；

例如：

function some_bloody_function($userId, $userName) {

}

7.常量：

全部字母都大寫，使用下劃線（_）分割單詞；