Далеко не всем программистам нравится составлять документацию. Поэтому регулярно возникают ситуации, когда ее вели недостаточно хорошо, либо она вовсе отсутствует. Это приводит к не самым приятным последствиям. Например, новоприбывшему программисту будет крайне сложно разобраться в проекте, который существует уже несколько лет, но разработчики не создали для него корректную базу документации. В этой статье мы поговорим о том, насколько важно фиксирование деталей и что происходит, когда оно отсутствует.
При создании продукта критически важно, чтобы все члены команды получали актуальную информацию об изменениях в проекте, а информация о новом функционале была зафиксирована. Это необходимо потому, что документация создает некое «общее пространство», в котором могут гармонично и эффективно работать все участники проекта. Так, не только новенькие программисты, но и любые члены команды смогут в любую секунду узнать все необходимое или свериться с текущим вектором работы.
Еще одним преимуществом можно назвать то, что с корректной документацией программисты будут «на одной волне». Это очень ценно, так как сокращает время на объяснения и оптимизирует коммуникацию. Когда появилась ошибка, программист может называть номер раздела, в котором описана проблемная функция, а не говорить размытыми формулировками. На поиск необходимого раздела уйдут секунды, ведь для этого нужно будет всего открыть документацию.
Помимо этого она способствует сохранению более четкого разграничения зон ответственности между программистами, что исключает возможность провисания какой-либо части из-за того, что: «Я думал, этим Игорь занимается». Тут же можно отметить, что невозможно хорошо выполнить какие-то требования, если они не были четко прописаны. Если же поставлены четкие, измеримые, реальные цели со сроками, гораздо легче оценивать полноту выполненной работы. Также подобное позволяет отбрасывать противоречивые требования и не оказаться через год с ворохом фрагментов, из которых невозможно вылепить цельный продукт.
Составление документации может повлечь за собой проблемы, но только в случае неправильного использования. Отличным примером тому становится ситуация, когда никто не заботится о обновлениях документов. Неактуальные комментарии будут вводить в заблуждение программистов, ведь код будет выполнять одни функции, а зафиксированы при этом совсем иные. При этом поддержание документации в актуальном состоянии предусматривает затраты рабочих часов. Так, написание кода и его описание занимает почти в два раза больше времени, чем просто написание кода. Но этот факт нельзя считать аргументом против составления документов, ведь в дальнейшем она поможет не только самому разработчику, но и новым членам команды.
Многие программисты не в восторге от ведения документации — это было бы пустяком, если бы из данного факта не вытекал другой. Не все разработчики умеют хорошо ее прописывать. Поэтому не выходит списать все на: «У каждой работы есть неприятные процессы». Для устранения ситуации, когда только создатель комментариев понимает их смысл, стоит разработать логичную систему. Также проблема может возникнуть на этапе хранения — описания теряют смысл, когда они находятся только у одного члена команды, а остальные должны каждый раз обращаться к нему за информацией.
В документировании нет надобности, если речь идет о верстке или каких-либо несложных проектах. Frontend разработчики часто считают, что их код не требует дополнительных объяснений и он вполне читабелен — если это действительно так, дополнительные объяснения могут только усложнять работу над проектом.
Заметили ошибку? Выделите ее и нажмите Ctrl+Enter, чтобы сообщить нам.
Ваш комментарий (необязательно):