|
Mar
14
|
Пишите документацию к проекту и коду!
 (1 голоса, средний балл: 5 из 5) Loading ... |
Иногда хочется просто прокричать это на весь мир, чтобы те, кто еще не слышал этого, наконец-то услышали.
С конца февраля я работаю в роли Senior PHP Developer над проектом (довольно большим и амбициозным), который 10 (!) месяцев разрабатывался абсолютно без ведения какой-либо документации (ну разве что диаграмма базы есть) к проекту и коду.
Естественно приходится постоянно пинать напарника, который 10 месяцев это разрабатывал. Он понимает важность написания документации, но такова была воля заказчика, так как ему надо было «быстрее получить результат, чтобы отчитаться перед инвесторами/заказчиками».
И дело даже не в том, что код плохой или что-то такое. Код нормальный, вменяемый, на Zend Framework, но ведь от этого легче не стает, так как система за 10 месяцев стала довольно огромной, а мне приходится вникать в нее с нуля.
К сожалению, очень часто выходит так, что рынок диктует условия, а не разработчик. Уже многократно проверно и подтверждалось. Однако всегда можно найти пару дней для того, чтобы задокументировать архитектуру проекта. Бес с ним уже с тем кодом, если он нормальный, то разобраться в нем не такое великое дело, хотя с комментариями конечно приятнее, удобнее и быстрее.
Поэтому, обращаюсь ко всем разработчикам и заказчикам: не пренебрегайте документацией, она поможет безболезненно войти в проект одному или нескольким разработчикам, когда вы поймете, что одного разработчика уже не достаточно.
Экономьте свое время и время вашей команды уже в самом начале, а не после того, как «припекло».
14.03.2009 в 20:04
Документация штука полезная, вот только я ни разу не видел, чтобы ее писал разработчик, когда он ведет проект в одиночку.
Каково было качество документации в твоих проектах, в которых ты работал раньше?
Очень часто на старте проекта не ясно насколько велика будет команда и будет ли она расти. Поэтому описываются только особенно сложные моменты.
Частенько документацию пишут именно пришедшие новички, потому как им это необходимо для работы, да и сстаршим товарищам позднее пригодится.
14.03.2009 в 21:49
Сколько разговоров было про это.
Сколько копий было сломано.
А что бы вы описали в своем текущем проекте в документации?
Что бы описали в том, что вы делали?
Как это хранили. актуализировали?
Ведь задним числом – все умные =)
14.03.2009 в 22:18
Я пишу документацию к любому проекту, имеющему размер больше 500 строк кода, даже когда работаю один. Это экономит время при повторных обращениях заказчика, позволяет эффективно повторно использовать код, резко облегчает передачу кода при расширении/смене команды.
Недавно перешел на проект, в котором уже прилично написано, а комментариев нет вообще. В итоге ко всему вновь написанному и как минимум к части модифицированного пишу комментарии, так как считаю “самодокументирующийся код” фикцией
14.03.2009 в 23:55
По-настоящему завидую. Я понимаю зачем это нужно, но комментарии в коде ставлю нечасто, только для того чтобы разбить функцию на логически блоги или описать неочевидные закономерности.
Случается и такое, причем нередко. В подобных случаях тоже вставляю комментарии, чтобы каждый раз снова не проводить исследование ЧУЖОГО кода. Но свойчастенько оставляю без пояснений.
16.03.2009 в 01:05
Владимир Рыбаков:
В больших проектах – на приличном уровне и это нормально.
Это не тот случай. Тут вопрос только стоял – “будут инвестиции или нет”, насколько я понимаю. А то, что команда будет и большая и будет расти – это очевидно из задач проекта – занять лидерские позиции в своем сегменте.
Согласен, так бывает. Но это не есть правильным, так, как никто не напишет документацию лучше человека, который проектировал и писал проект. По-моему это очевидно.
milo:
Описал бы все, что можно. От целей проекта до структуры базы. Это важная информация. Особенно вопрос архитектуры очень важен.
Хранил бы в SVN, как и весь проект хранится. Актуализировал бы точно также. Хотя архитектурные изменения происходят очень не часто, поэтому вопрос актуализации – довольно смешной на самом деле. Если приходится часто вносить изменения в архитектуру, значит “это какие-то не правильные пчёлы и они делают не правильный мёд” – тоесть архитектор проекта зря ест свой хлеб.
20.04.2009 в 01:08
Да, тема близка. Последнее время часто занимаюсь проектами, которые делали до меня, в общей сложности около 20 сайтов мне передали после какого-то свободного художника.
Комментариев нет вообще. Нет отступов, табов, вообще все написано в кучу, не понятно где что начинается, где заканчивается, в каком файле что хранится, несколько объектов могут лежать в одном файле и название его особо ни о чем не говорит, кругом HTML в перемешку с PHP, ужас.
Сам стараюсь писать комментарии по правилам phpDoc.
Но встретился опять же с еще одной проблемой – комментарии и документация – это время. Заказчик бывает очень нетерпеливый и ему нужно быстрее, он даже жаловался – почему тот, что до тебя был, он делал быстрее. И я никак не могу ему объяснить, что он там ужас понаделал.
Вот сейчас проект пишу и почти без комментов даже, только для себя немного. Просто ужасно не успеваю, у заказчика сроки фантастические, очень быстро нужно, работаю по выходным, пишу ночью, пишу днем, почти не сплю. Больше браться за такое дело желания нет, но, раз уж взялся – это надо довести до конца.
P.S. Очень понравился блог, добавил в закладки, добавил RSS-ридер.
Написал пост у себя в блоге на ту же тему, указал ссылку на Ваш пост у себя.
Удачи.