21 ошибка программиста PHP. Часть 1 - Недостаточно либо излишне комментированный текст

Written on . Posted in PHP

ОГЛАВЛЕНИЕ

Страница 4 из 9

19. Недостаточно либо излишне комментированный текст

Плохо документированный текст программы является признаком эгоистичного программиста. Результатом попытки анализа вашей программы с целью внесения улучшений будет только головная боль. Причем все программисты считают самодокументированный код хорошим тоном, но сами крайне редко пишут комментарии.

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

<?php // Начало кода

$age = 18; // Возраст равен 18
$age++; // Увеличим $age на один год

// Напечатаем приветствие
print "Вам сейчас 19 лет, и это значит, что Вам уже было:";
print "\n<br>\n<br>\n";

// Цикл "для" чтобы вывести все
// предыдущие значения возраста
for ($idx = 0; $idx < $age; $idx++)
  {
    // Напечатаем каждое значение возраста
    print "$idx лет\n<br>\n";
  }
// Конец кода
?>

И все-таки: где золотая середина?

Итак, какой же объем комментариев следует помещать в скрипт?! Это зависит от многого: от времени, которым вы располагаете, от политики компании, сложности проекта и т.д. Тем не менее, запомните несколько основных принципов, которым надо следовать при написании программ вне зависимости от вашего решения:

  • Перед телом функции всегда помещайте комментарий - назначение функции.
  • Добавляйте комментарии в сомнительных участках кода, когда нет уверенности, что он будет работать как надо.
  • Если назначение кода неочевидно, внесите информацию о предназначении этого участка. Вы же потом воспользуетесь этим комментарием.
  • Избегайте комментарии вида # - используйте только /* */ либо //.

Следующий пример иллюстрирует хороший стиль комментариев:

<?php
  // Random_Numbers.lib
  // Генерация случайных чисел различного типа

  mt_srand((double)microtime()*1000000);

  //
  // mixed random_element(array $elements[, array weights]) 
  // Возвращает случайный элемент массива-аргумента
  // Массив weights содержит относительные вероятности
  // выборки элементов
  //

  function random_element ($elements, $weights = array())
  {

    // Для корректного функционирования этого алгоритма
    // количество элементов массива должно быть равным
    // количеству элементов массива относительных вероятностей

    if (count ($weights) == count ($elements)) {
      foreach ($elements as $element) {
        foreach ($weights as $idx) {

          // Примечание: мы не используем $idx, потому что
          // нам не нужен доступ к отдельным элементам
          // массива weights

          $randomAr[] = $element;
        }
      }
    }
    else {
      $randomAr = $elements;
    }

    $random_element = mt_rand (0, count ($randomAr) - 1);
    return $randomAr [$random_element];
  }
?>
php форум