Документирование неявных входных параметров, таких как $ _SESSION - PullRequest
Новая
       9

Документирование неявных входных параметров, таких как $ _SESSION

3 голосов
/ 10 октября 2010

Если функция полагается на $_SESSION['some_var'], тогда заголовок комментария проясняет это.Как ты делаешь это?Просто как текст или как?

Или даже @param?

Ответы [ 4 ]

4 голосов
/ 10 октября 2010

Возможно, вы можете использовать @ использует для документирования суперглобальных

2 голосов
/ 11 октября 2010

@ global имеет два применения: для обозначения определения глобальной переменной и для выделения использования глобала в методе.Это второе использование соответствует вашему варианту использования.

Однако, при условии, что вы ссылаетесь на $ _ SESSION ['some_var'] непосредственно в этом методе, и никогда не обозначаете его через " global "ключевое слово, возможно, что тег phpDocumentor @ global не найдет его при анализе метода.Таким образом, @ использует , вероятно, является лучшей альтернативой в качестве средства, чтобы подчеркнуть зависимость метода от этого суперглобального.

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

2 голосов
/ 10 октября 2010

Ух ты, я даже не думал об этом.Я даже не документирую подобные вещи.Я бы сказал, что просто изложить это в деталях метода, как 

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

. Мне кажется, это наиболее разумно.,Я думаю, что @param должен ссылаться только на параметры метода, переданные методу.Я не знаю ни одной @note.

1 голос
/ 12 января 2011

Если ваш код зависит от того, что для работы должно присутствовать что-то глобальное или внешнее (например, для его установки требуется sqlite), вы можете использовать @use в качестве Не упоминалось .

ОДНАКО ...

В целом, я бы сказал, что плохая практика - заполнять функцию или использовать глобальные переменные (или использовать суперглобальные переменные), так как это нарушает инкапсуляцию функции и создает сильную зависимость между кодом внутри функции и снаружи. .

Если какой-либо код, внешний по отношению к функции, должен создавать или обращаться к этим глобальным переменным, значения должны вместо этого передаваться в качестве параметров функции.

Например, вместо 

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.

Как только ваш код немного растет, его поддержка, совместное использование, отладка и расширение такого рода кода становятся кошмаром ...

...