самодокументированный код — PHP: использование ключей массива для определения аргументов функций
Я определяю пользователя многими функциями, и некоторые из них имеют шесть, десять или даже больше аргументов. Чтение моего кода становится трудным, когда я забываю, каковы аргументы функции или в каком порядке они идут. Я разработал способ справиться с этим, заменив все аргументы одним массивом и используя ключи массива в качестве меток для каждый аргумент. Так, например, вместо
function MyFunction(string $sSayThis, int $nRepeatTimes, bool $bLoud = $false) {...}
У меня сейчас
function MyFunction(array $args)
{$sSayThis = $args['sSayThis']); CheckType($sSayThis, 'string');
$nRepeatTimes = $args['nRepeatTimes']); CheckType($nRepeatTimes, 'int');
$bLoud = (IsSet($args['bLoud']) ? $args['bLoud'] : false); CheckType($bLoud, 'bool');
...
}
Вызов этой функции вместо
MyFunction('Hello', 3, true);
теперь выглядит
MyFunction(array('sSayThis' => 'Hello', 'nRepeatTimes' => 3, 'bLoud' => true));
Это вряд ли необходимо, когда есть только три аргумента, как в этом примере, но это может быть очень полезно при чтении кода для функции с шестью или десятью аргументами! Кроме того, если мне нужно только передать значение для десятого аргумента и использовать значения по умолчанию для всех необязательных аргументов до этого, я могу просто пропустить эти другие аргументы из вызова вместо передачи серии , '' для них.
Это взломать, и это кажется уродливым. Но это помогает сделать мой код самодокументированным и легким для чтения.
Я знаю, что есть IDE, которые дают мне подсказки аргументов, но я использую Notepad ++, который этого не делает.
Эта идея обсуждается в аналогичном вопросе, заданном в прошлом году, Аргументы функции PHP — использовать массив или нет?, но этот вопрос не показывает, как выглядят вызовы функций, что является наиболее важной частью вопроса. Некоторые люди, отвечая на этот вопрос, сказали, что функции никогда не нужно десять аргументов, а наличие такого количества указывает на плохой дизайн. Я понимаю эту проблему, но иногда алгоритму просто нужно много информации.
Что-то не так с этим подходом, или есть лучший способ самостоятельно документировать эти вызовы функций?
Решение
ИМХО, вряд ли есть разница с точки зрения читабельности кода. Второй подход, однако, добавляет некоторые новые недостатки:
- Он больше не использует подсказки типа PHP
- Ваша IDE больше не может использовать информацию, проанализированную из кода и аннотаций, для предоставления полезных советов или автозаполнения.
Функции с большим количеством аргументов обычно являются индикатором унаследованного кода, который вышел за пределы своего дизайна. Я думаю, что это требует некоторого рефакторинга, например:
class Speaker
{
/**
* @var string
*/
private $sayThis;
/**
* @var int
*/
private $repeatTimes;
/**
* @var bool
*/
private $loud;
/**
* @param string $sayThis
*/
public function __construct(string $sayThis)
{
$this->sayThis = $sayThis;
}
public function times(int $repeatTimes)
{
$this->repeatTimes = $repeatTimes;
return $this;
}
public function loud(bool $loud = false)
{
$this->loud = $loud;
return $this;
}
public function say()
{
$output = str_repeat($this->sayThis, $this->repeatTimes);
echo $this->loud
? mb_strtoupper($output)
: $output;
}
}
(new Speaker('Foo'))
->times(4)
->loud(true)
->say();
Как видите, я также избавился от венгерской нотации.
Другие решения
Я бы уволил тебя. Просто шучу. А если серьезно, то это свенгали. Вы не должны пытаться изобрести что-то совершенно новое для проблемы, которая уже решена. Вы будете путать любого, кто пытается прочитать ваш код, и вы настроите себя на бесполезность в будущем. Это не основано на мнении, потому что есть стандартные способы борьбы с этим.
Изучите ООП, особенно интерфейсы. Интерфейс определяет «контракт» того, что объект ожидает получить. [Это входы, которые вы постоянно забываете]. Если у вас есть функция, которая принимает 10 аргументов, вы должны уменьшить свою логику, чтобы функция принимала ОБЪЕКТ с 10 свойствами. Затем постройте объект из других объектов. То, что у вас останется, это 5 или около того [я предполагаю, что свойства как-то связаны, так что это не будет 10 объектов], с которыми можно разобраться всего за несколько строк кода, что делает его легко читаемым.