Re: [請益] 關於註解的用法

[liaosankai (低溫烘焙)]

※ 引述《edash (團長)》之銘言：
: PHP provides several ways to include comments within your code, all of which
: are borrowed from existing languages such as C, C++, and the Unix shell.
: In general, use C-style comments to comment out code, and C++-style comments
: to comment on code.
: 節錄書本其中一段，主要是第二句的問題，書中將out與on使用斜體表示。根據該書
: 說法，C-style指的是/*...*/，C++-style指的是//
: 從字面上看來，個人猜測第二段的意思應該是指C-style註解用在程式之外，也就是
: 不跟程式碼夾雜在一起。C++-style註解用在程式碼之中，也就是註解特定行的程式碼。
: 不太確定自己的解讀是否正確，請板友多多指教，謝謝。

這篇可能未能針對你的問題回答，但對於註解的部分，僅分享我個人
在 PHP 註解使用上的經驗分享來提供一些參考

PHP 提供三種註解方式

1) 區塊 /* ... */

通常使用在變數、類別或函式前面的區塊註解，並給予帶有 "@" 開頭的特殊
註解字串，方便 phpDocumentor、doxygen 這類工具自動產生 api 文件。


    /**
     * 類別註解
     *
     * @copyright (c) 2013, Liao San-Kai
     */
    class Demo {

       /**
        * 變數註解
        *
        * @var string
        */
        private $author;

       /**
        * 函式註解
        *
        * @param int $num 參數說明
        * @return void
        */
        public function show($num) {

        }
   }



2) 單行 //

大部分使用在對於程式碼的說明，盡可能將當時的想法，為什麼
要這麼做寫出來。即便說明可能很長，也要使用多個 // 來
註解，而不直接用 /* */。

    function test($param) {

        // 這是一行對於程式碼的註解
        $data = is_array($param) ? $param : array();


        // 這段是一個比較詳細的註解，因為註解內容相
        // 對比較長，所以需要分段來撰寫。但不使用/**/
        // 僅使用多個單行來註解
        foreach($data as $key => $value) {
            // ... (略) ...
        }
    }



3) 特殊 #

雖然和 "//" 一樣是單行註解，但我將它使用在於設定檔臨時註解，也就是
它可能在未來還會透過消取註解來重新啟用。例如下列範例，我透過 # 註解
來將 auth、codebench 模組暫停使用。

    Kohana::modules(array(
        "image" => MODPATH . "image",
        #"auth" => MODPATH . "auth",
        "cache" => MODPATH . "cache",
        "orm" => MODPATH . "orm",
        #"codebench" => MODPATH . "codebench",
    ));

--
歡迎來我的網誌看看
@ http://blog.liaosankai.com


--
※ 發信站: 批踢踢實業坊(ptt.cc) 
◆ From: 203.203.50.60
→ Canboo:範圍程式碼註解我會使用if(0){}包起來，不會使用//加在每行
→ liaosankai:不太懂上面的意思，能否能進一步說明？
推 LaPass:1F那個我懂....
→ LaPass:簡單來講，就是有些地方很難把他註解掉，又不好直接拿掉那
→ LaPass:樣，例如客戶說不要XX功能，或是畫面上不要顯示OO之類的，
→ LaPass:這時候就會在那一段的前後用一個 if(0){  不要的內容  }
→ LaPass:直接繞過去這樣....
→ LaPass:然後，html中夾雜一堆server side的程式語言的地方我覺得最
→ LaPass:難搞，因為真的很難把其中某段註解掉....
→ LaPass:jsp跟php都一樣...
→ liaosankai:啊…原來是這樣，感謝LaPass的說明。