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

Question

如果一个函数依赖，$_SESSION['some_var']那么标头注释会清楚地表明这一点。你怎么做呢？就像文本一样，还是什么？

甚至@param？

Answer 1

你也许可以使用@uses来记录超全局变量

Answer 2

@global有两种用法：表示全局变量的定义，以及突出显示全局变量在方法中的用法。第二种用法适合您的用例。

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

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

Answer 3

哇，我从来没想过。我什至不做这样的事情。我会说只是在方法细节中说明它

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

对我来说最有意义。

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

Answer 4

如果您的代码依赖于全局或外部的东西才能工作（例如，它需要安装 sqlite），您可以使用 @use as Nev 提到的。

然而...

一般来说，我会说让函数填充或使用全局变量（或使用超全局变量）是一种不好的做法，因为它破坏了函数的封装并在函数内部和外部的代码之间产生了强烈的依赖关系。

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

例如，而不是

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