- Часто ли вы пишете документацию или хотя бы подробные комментарии к своему коду?
- Как вы себя чувствуете когда вам приходится работать над проектом, который был написан другим человеком и в нем нет никаких комментариев, а код достаточно большой?
- Во время разработки вы не писали документацию? Прошел год и вам пришлось вернуться к этому проекту? Как ощущения? =)
В последнее время мне часто приходится буквально "разгребать" непонятный код раскиданный по непонятно как структурированным файлам. Дело в том, что я продолжаю разработку проектов, которые когда-то были начаты другими людьми.
Люди эти, к моему глубокому сожалению не обременили себя написанием хотябы скромных комментариев к коду, либо не нашли на это времени.
Так сильно задевает меня эта тема и так много проблем порой доставляет недокументированный код, а если он еще и "кривой", то только на то, чтобы понять что к чему уходят дни, не говоря уже о том, когда можно будет приступить к продолжению работы над проектом.
И ладно бы, я человек спокойный и терпеливый. Ну разобрался бы в итоге. Но существует заказчик, которому никак не объяснить почему вроде бы не такая сложная задача не может быть решена за один день и почему предыдущий разработчик (автор того самого недокументированного кривого кода) делал все быстрее. Заказчик не может понять, что мне нужно переварить груду этого толком неструктурированного кода, чтобы сделать умозаключения о дальнейшей разработке. Мало того, когда заказчик задает вопросы о сроках разработки на начальном этапе передачи проекта, то в данном случае я затрудняюсь ответить - еще не ясно что меня ждет дальше и насколько удобоваримый код я буду рад лицезреть.
Поэтому совет простой, а даже не совет, а просьба: - Пожалуйста, друзья по несчастью, давайте хотябы комментировать код, пусть даже комментарии не придерживаются стандартов документирования, просто, чтобы понятно было.
Честно признаюсь, этот крик души не одинок! Не хочу копировать посты, просто присоединяюсь к замечательному блогу Станислава Малкина.
Люди эти, к моему глубокому сожалению не обременили себя написанием хотябы скромных комментариев к коду, либо не нашли на это времени.
Так сильно задевает меня эта тема и так много проблем порой доставляет недокументированный код, а если он еще и "кривой", то только на то, чтобы понять что к чему уходят дни, не говоря уже о том, когда можно будет приступить к продолжению работы над проектом.
И ладно бы, я человек спокойный и терпеливый. Ну разобрался бы в итоге. Но существует заказчик, которому никак не объяснить почему вроде бы не такая сложная задача не может быть решена за один день и почему предыдущий разработчик (автор того самого недокументированного кривого кода) делал все быстрее. Заказчик не может понять, что мне нужно переварить груду этого толком неструктурированного кода, чтобы сделать умозаключения о дальнейшей разработке. Мало того, когда заказчик задает вопросы о сроках разработки на начальном этапе передачи проекта, то в данном случае я затрудняюсь ответить - еще не ясно что меня ждет дальше и насколько удобоваримый код я буду рад лицезреть.
Поэтому совет простой, а даже не совет, а просьба: - Пожалуйста, друзья по несчастью, давайте хотябы комментировать код, пусть даже комментарии не придерживаются стандартов документирования, просто, чтобы понятно было.
Честно признаюсь, этот крик души не одинок! Не хочу копировать посты, просто присоединяюсь к замечательному блогу Станислава Малкина.
в экстремальном программировании есть идея о том, что код должен быть самодокументированным, то есть хорошо структурированным и простым. мне эта идея нравится и я почти никогда не пишу комментарии.
ОтветитьУдалитьНереально при очень большом проекте. Когда кучи объектов и все это взаимосвязано - уйдет много времени разбираться. Встречаюсь с очень грамотным кодом, но не было у кодера времени документировать - благо, грамотно написано и разобраться можно, но сколько времени ушло. А когда пишешь с использованием инструментов для документирования - экономит кучу времени. JavaDoc, PHPDoc - и у тебя готовый справочник по всем классам. А если классов 100-200 или больше? Я посмотрю на понятный код когда времени мало, денег мало, а кода, пусть грамотного, но просто десятки мегабайт.
ОтветитьУдалить