27 окт. 2011 г.

"Я не пишу комментарии, потому что мой код самодокументирован"

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

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

Но должны быть комментарии кода на человеческом языке:
  • На уровне классов.
  • На уровне методов.
  • На уровне логических кусков кода.
  • На уровне строк кода, в которых делается какая-то "магия".
Когда новый программист входит в проект, он должен понимать о том, "как тут все работает", не прочитывая пару сотен строк кода и делая из имен переменных логические выводы, а прочитав что-то вроде "Юзер может иметь не более 3 проектов (см. ТЗ, пункт 3.2.4)". Он должен понять, что за функция, какие параметры принимает и что возвращает, прочитав описание функции, а не ее код.

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

Комментариев нет :

Отправить комментарий