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

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

Перед телом функции всегда помещайте комментарий – назначение функции.

Добавляйте комментарии в сомнительных участках кода, когда нет уверенности, что он будет работать как надо.

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

Избегайте комментарии вида # - используйте только /* */ либо //.

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

<?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]; } ?>

Содержание раздела