Question

如果一个函数依赖于$_SESSION['some_var']，那么标题会注释掉以清除它。你怎么做呢？就像文字一样，还是什么？

甚至@param？

Answer 1

您可以使用@uses来记录超级全球

Answer 2

哇，我从来没有想过这个。我甚至没有这样的东西。我会说只是在方法细节中说明它

/**
 * Takes the some_var session variable and uses it to solve world hunger
 * @return food
 */

对我来说最有意义。

有@global，但这似乎表明创建了一个全局变量。我认为@param应该只引用传递给方法的方法参数。我知道没有@note。

Answer 3

@global 有两个用法：表示全局var的定义，并突出显示方法中的全局用法。第二种用法适合您的用例。

但是，假设您直接在该方法中引用 $ _ SESSION ['some_var'] ，并且从未通过“全局”关键字表示它，则可能是解析方法时，phpDocumentor的 @global 标记不会找到它。因此， @uses 可能是强调该方法依赖超全球的最佳选择。

[1] - http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.global.pkg.html

Answer 4

如果您的代码依赖于某些全局或外部的东西，以便工作（例如，它需要安装sqlite），您可以使用@use作为Nev mentioned。

<强>无论其...

一般来说，我会说有一个函数填充或使用全局变量（或使用超全局变量）是一个坏习惯，因为它打破了函数的封装并在函数内部和外部的代码之间创建了强依赖性

如果函数外部的任何代码应该创建或访问那些全局变量，那么值应该作为参数传递给函数。

例如，而不是

function doMagic(){
    if ($_SESSION['use_black_magic'] == true){ // var coming from the outside
      $_SESSION['magic_results'] = 'dead chicken';
    }else{
      $_SESSION['magic_results'] = 'unicorn';
    }
}

$_SESSION['use_black_magic'] = false;
doMagic();
echo $_SESSION['magic_results']; // (unicorn) variable set within doMagic()

应该是

function doMagic( $use_black_magic = true ){
    if ($use_black_magic == true){
      return 'dead chicken';
    }else{
      return 'unicorn';
    }
}

$magic_results = doMagic( false );
echo $magic_results; // unicorn

这样，doMagic（）不需要知道结果存储的位置，也不需要知道查找参数值的位置。而外部代码，不需要知道函数doMagic（）正在使用$ _SESSION变量。

只要你的代码增长一点点，维护，共享，调试和扩展这种代码就会变成一场噩梦......

http://en.wikipedia.org/wiki/Separation_of_concerns

记录隐式输入参数，例如$ _SESSION

4 个答案: