Подписка ReLife
Документируйте свой код
Это самый очевидный пункт, и тот, который никто не любит делать. Кажется, что это пустая трата времени, но, потратив несколько секунд на то, чтобы явно сказать, что все делает, вы сэкономите всем время и головную боль в долгосрочной перспективе. То, что сейчас кажется интуитивным, может занять несколько минут для интерпретации в будущем, в зависимости от стилистических различий и знакомства с системой. Ваша документация может сэкономить кому-то час или два копания в коде через несколько месяцев.
Выпускаете фреймворк или библиотеку для общественности? Пожалуйста, предоставьте документацию. Даже просто в коде. Никто не хочет разбирать всю систему каждый раз, когда возникает простая задача.
Используйте описательные имена переменных
$product_discounts > $pDiscounts > $pd
Все это в любом случае компилируется в таблицу символов. Используйте имена переменных, которые четко описывают их назначение и содержимое. Это самая дешевая и эффективная документация, которую вы можете сделать. Взгляните на это:
// получить скидки на каждый продукт
foreach($product_list как $product_id) {
$product_discounts[] = $discount_model->get_discounts_for($product_id);
}
Хотя это может быть не оптимально, но это все равно передает суть. Хорошо читается, не так ли? Теперь попробуйте это:
foreach($plist as $p) $pd[]=$dm->dFor($p);
Печатать теперь меньше времени? Конечно. Сделает ли это ваших нынешних и будущих соразработчиков очень недовольными? Да. Не делайте так.
То же самое касается имен функций. Если вы обнаруживаете, что документируете функцию с надписью «Делает то, что написано на упаковке», вы делаете это правильно (конечно, вам все равно следует документировать параметры и возвращаемые значения).
Соблюдайте правила системы
Это коротко. Если вы работаете в среде MVC, не помещайте несколько сотен строк логики контроллера в представление. Не помещайте логику модели в контроллер или представление.
В общем, если все структурировано определенным образом, так и оставайтесь, если только у вас нет очень убедительных причин поступать иначе (и если они у вас есть, задокументируйте их).
Проводите рефакторинг повторяющегося кода
Если вы обнаружили, что копируете и вставляете код, подумайте о том, чтобы сделать его функцией. То же самое касается и случая, когда определенный набор задач может быть описан функцией.
Вот пример:
$this->collection[] = $this->load->something('first');
$this->collection[] = $this->load->something('second');
$this->collection[] = $this->load->something('third');
$this->collection[] = $this->load->something('fourth');
// и так далее…
Переписываем:
foreach(array('first','second','third','fourth') as $thing)
$this->collection[] = $this->load->something($thing);
Переписывание функции (общее):
// если у вас есть доступ к $registry из этой области, он вам не нужен…
функция load_things(&$registry, $thing_array) {
foreach($thing_array as $thing)
$registry->collection[] = $registry->load->something($thing);
}
load_things($this, array('first','second','third','fourth'));
Конечно, если у вас там сотни элементов, вам придется перебрать их все, либо делать некоторые оптимизации.
Несколько строк допустимы
Разбейте на несколько строк следующую информацию, если ваш язык это позволяет: строки, массивы, операторы SQL и длинные вызовы функций.
Возьмем, к примеру, SQL-код: слчуется, сейчас он довольно короткий, но если бы в нем было еще несколько объединений и ограничений, его было бы сложно уместить в одну строку.
В случае длинных вызовов функций рассмотрите возможность использования ассоциативного массива (или словаря) для передачи дополнительных параметров. Они имеют дополнительное преимущество в виде именования того, что они передают.
Чем больше вы можете сделать, чтобы все было понятно, тем лучше. Никто не любит прокручивать связанную строку длиной 1000+ символов всего в одной статье.
Комментарии