Вагиф Абилов (object) wrote,
Вагиф Абилов
object

Документация программного кода

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

Честно говоря, меня это довольно сильно обескуражило. С одной стороны - мое участие в проекте ограничено считанными днями, не в последнюю (если не в первую) очередь из-за моей дороговизны, из-за чего я стараюсь выжать из себя за эти дни как можно больше работающего и оттестированного кода, с другой - оказывается, часть этого времени стоит посвятить написанию комментариев. Не юнит-тестов, а комментариев.

Не могу не процитировать: "Design is documented by creating unit tests as working examples of how to use each part of the code." Robert Martin a.k.a. Uncle Bob.

Именно это я и делаю. Тесты пишутся не только для проверки корректности алгоритма. Часть тестов пишется как пример использования API. Причем в отличие от комментария, тест не может незаметно устареть.

Сам я, знакомясь с новым кодом, если он неплохо покрыт юнит-тестами, никакую другую документацию обычно не смотрю.

P.S. Don't get me wrong. Комментарии необходимы для пояснения неочевидных выборов или отклонений от стандартных ходов. Но по моему личному опыту на такое приходится не больше 10 процентов кода, вот это и надо комментировать, а не все подряд.
Subscribe
  • Post a new comment

    Error

    default userpic

    Your reply will be screened

    Your IP address will be recorded 

    When you submit the form an invisible reCAPTCHA check will be performed.
    You must follow the Privacy Policy and Google Terms of use.
  • 16 comments