Чем пожертвовать, DRY или самодокументируемым кодом?

Question

[Алексей Николаев]

Доброй ночи.
Есть приложение, недавно закончил рефакторинг. Появилось много классов, неймспейсов и еще больше функций, в том числе и однострочных. Я старался сделать код самодокументируемым, посему часто можно встретить функции вроде:

private function is_map_have_passed_param($map, $param) {
    return is_array($map) && isset($map[$param]);
}

private function get_array_of_default_values_from($string) {
    return explode('-', $string);
}

Проблема в том, что подобные атомарные функции расплодились по всем классам, и в некоторых местах нарушают DRY - есть даже почти одинаковые функции, но названные по-разному в угоду самодокументируемости. Нельзя просто взять и заменить обратно ту же get_array_of_default_values_from - будет непонятно, что получается из разбиения строки. Потребуется комментарий, а, как известно, лучший комментарий - тот, без которого удалось обойтись.

Поэтому я придумал воспользоваться трейтами, и вынести все атомарные функции в трейт. Это будет 100% DRY, но самодокументируемость скорее всего пострадает: мне придется объединить несколько функций, делающих одно и то же, но имеющие разные имена, в одну универсальную.

Чем лучше пожертвовать? И можно ли усесться на два стула сразу?

Answer 1

[nirvimel]

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

$x = is_array($map) && isset($map[$param]) /* is map have passed param */
$y = explode('-', $defaults) /* get defaults int range */

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

Answer 2

[Stalker_RED]

if (!empty($map[$param])) { // здесь комментарий для тех, кто не знает что такое empty()
}

$default_values = explode('-', $string); (здесь комментарий не нужен, эта строка и так неплохо "документируется" благодаря имени переменной.)

Вообще, комментарии лучше писать по бизнес-логике, типа
/**
* этот метод красит котят в розовый
*/
бу-бу-бу
бу-бу-бу
...
10 строк кода

А вводить однострочные функции ради комментария - странная идея.