О комментариях в коде.
Часто работаю с чужим кодом и вижу много попыток разработчиков комментировать код. Вещи довольно очевидные, но вижу их постоянно. Буквально только что наткнулся на очередной перл и меня "прорвало", захотелось высказаться.
Комментирование кода - крайне необходимо, но чтобы это грамотно делать, нужно хорошо знать свой код и понимать места, которые вызывают трудность понимания.
Разработчик, который будет смотреть ваш код - не дурак, и не нужно оставлять комментарии вроде
или
Мы все прекрасно знакомы с SoapClient и знаем как работают исключения, не нужно для этого оставлять дополнительные комментарии. Комментарии нужно писать там, где из названия функций, переменных и действий над ними не ясна суть происходящего (именно суть, далее опишу, что имею ввиду).
Например:
Все прекрасно понимают, что тут происходит, но зачем это делается (суть) не ясно вовсе. И такой код нужно снабдить комментарием вроде: в учетной системе не могут быть нулевые значения (такова специфика бизнеса), поэтому запишем любое небольшое значение не больше 1 рубля.
Кроме как в виде комментария данную особенность не отразить никак, но в основном комментировать код (упрощать его понимание) можно просто грамотно называя методы и переменные.
Этот кусок кода НУЖНО обернуть в функцию, название которого отражает назначение кода.
Часто работаю с чужим кодом и вижу много попыток разработчиков комментировать код. Вещи довольно очевидные, но вижу их постоянно. Буквально только что наткнулся на очередной перл и меня "прорвало", захотелось высказаться.
Комментирование кода - крайне необходимо, но чтобы это грамотно делать, нужно хорошо знать свой код и понимать места, которые вызывают трудность понимания.
Разработчик, который будет смотреть ваш код - не дурак, и не нужно оставлять комментарии вроде
// Soap-подключение к сервису $this->SOAP_CLIENT = new SoapClient('https://' . $host); |
catch (Exception $ex) { //ошибка в работе } |
Например:
if ($sales == 0) $sales = 0.1; |
Кроме как в виде комментария данную особенность не отразить никак, но в основном комментировать код (упрощать его понимание) можно просто грамотно называя методы и переменные.
for($i=2;$i<=$n;$i++) $r *= $i; |
function calculateFactorial() { .... } |