作者liaosankai (低温烘焙)
看板PHP
标题Re: [请益] 关於注解的用法
时间Wed Sep 18 11:26:54 2013
※ 引述《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
1F：→ Canboo:范围程式码注解我会使用if(0){}包起来，不会使用//加在每行 09/18 15:54
2F：→ liaosankai:不太懂上面的意思，能否能进一步说明？ 09/18 22:30
3F：推 LaPass:1F那个我懂.... 09/18 22:41
4F：→ LaPass:简单来讲，就是有些地方很难把他注解掉，又不好直接拿掉那 09/18 22:43
5F：→ LaPass:样，例如客户说不要XX功能，或是画面上不要显示OO之类的， 09/18 22:44
6F：→ LaPass:这时候就会在那一段的前後用一个 if(0){ 不要的内容 } 09/18 22:45
7F：→ LaPass:直接绕过去这样.... 09/18 22:45
8F：→ LaPass:然後，html中夹杂一堆server side的程式语言的地方我觉得最 09/18 22:46
9F：→ LaPass:难搞，因为真的很难把其中某段注解掉.... 09/18 22:46
10F：→ LaPass:jsp跟php都一样... 09/18 22:46
11F：→ liaosankai:啊…原来是这样，感谢LaPass的说明。 09/19 10:05