Лучше программировать, чем документировать

06.04.2014 22:17

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

Если это не код, то его нельзя обработать через компилятор, чтобы убедиться в его смысловой ценности.
Если это не код, его нельзя выполнить, а, следовательно, его никогда нельзя будет использовать для завершения чего-либо.
Если это не код, его нельзя протестировать, а, следовательно, нет ни единой возможности доказать его правдивость и корректность.
И сообщество Agile преуменьшает роль документации в своем манифесте: рабочий программный продукт вместо исчерпывающей документации.

Итак, вся ли документация такая плохая? Думаю, вы сами знаете ответ.

Зачем что-то записывать?

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

Вспоминая, почему вы приняли решение

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

Однажды, спустя долгое время после принятия таких решений, кто-нибудь из членов команды (обычно кто-то из новичков, они такие надоедливые, не так ли?) задаст вопрос “Почему мы это делаем?” Какой ответ они услышат?

Если хотя бы у одного из членов команды хорошая память, и он работает в проекте с самого его начала, то новичок, скорее всего, узнает об истинной причине выполняемых им действий. Но в большинстве случаев, боюсь, ответ будет следующим: “Потому что мы всегда делаем именно так”. Разумеется, это далеко не тот ответ, который бы нам хотелось услышать.

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

В конце концов, что может пойти не так? Ну, как оказывается … не так уж и мало. Например:

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

Всех этих последствий можно избежать, если выделить всего лишь чуточку времени для записи нужной информации. Когда ваша команда принимает решение, изменяющее ход работы, запишите дату принятия этого решения, например, в базе знаний, и его логическое обоснование (преуспев в этом деле, у вас возможно даже появится процесс принятия решений, создающий артефакты, на которые вы впоследствии сможете указать). Позже, когда кто-нибудь задаст вопрос: “почему вы поступаете именно таким образом или используете именно этот инструмент”, вы сможете с уверенностью ответить на этот вопрос.

Подготовка к автоматизации надоедливого процесса

Разработчики довольно часто находят процессы, которые им бы хотелось автоматизировать. К ним относятся часто повторяющиеся процессы со значительной временными затратами. Тем не менее, я все чаще сталкиваюсь с ручными процессами, которые обладают высокой частотой исполнения (возможно, один раз в несколько недель) и включают в себя целый ряд шагов, обязательно выполняемых в определенной последовательности. И если никто не побеспокоится о записи информации об этом процессе, с высокой долей вероятности он будет выполнен неверно, либо же будут перепутаны шаги, что в свою очередь приведет к потере драгоценного времени. Более того, не существует ни одного практического способа автоматизации процесса без предварительного записывания информации о предпринимаемых шагах.

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

Оригинал статьи: http://www.infoq.com/articles/id-rather-be-coding-writing-things-down

Автор: Nate McKie

Попробуйте сейчас!