Итак, начну, пожалуй, с документации.
Кто же не любит писать множество строк документации?
Я, например, не особо. Но как только вы заходите в область, где ваш код становиться публичным (public), который может использоваться в разных частях вашего проекта, или, даже, в сторонних проектах, если код будет предоставляться в фреймворках, то наличие или отсутствие документации становиться критическим фактором.
Ввиду того, что я мобильный разработчик, приведу пару примеров из мобильных проектов. Первый, и наиболее общий пример для всех проектов - локализация. Она представляет из себя, в лучшем случае, ассоциированные кодовые фразы, и чем крупнее проект, тем длиннее эта фраза и тем менее понятно, в какой части кода её надо использовать.
SHOW_TC_SINGLE_EPISODE_PICKER_HEADER_TITLEПро это название я бы сказал: “Во время разработки понятно, к какому экрану и какому компоненту в нём относится эта строка”
no_payment_now А тут в первый раз я сказал: “Вроде бы это был текст для описания над кнопкой. Хотя, может, он для промо баннера”.
Строка из первого примера значительно лучше, ведь по ней можно понять, что она из себя представляет и где она применяется. Однако проект был настолько крупный, что элементов Episode Picker оказалось четыре, и к какому именно относилась эта строка, которую автор экрана (я) благополучно забыл добавить вместо заглушки, в том числе, как и документацию для этой строки в файле локализации. Как итог, разработчику, который занимался фиксом данного бага (не я), потребовалось не 10-15 минут на банальную замену “label” на необходимую строку, а около часа, и созвон с тестировщиком, чтобы разобраться, который именно экран требует исправления.
Вторая же строка хоть и не даёт много информации своим названием, уже имела добавленную документацию, благодаря которой было однозначно понятно, где применяется эта строка:
///For usage in subsribe_page.dart
///component subButtonText
///in eng, translates into ‘No payment now’ Второй пример более рассчитан на переиспользование кода, чем на предотвращение ошибок.
Пример приведу один, однако я думаю, он крайне явно покажет необходимость документирования кода. В рамках работы был разработан прототип для интеграции управления приложением с помощью глаз. Было выведено простое API для добавления управления, однако оно всё равно состояло из определённого процесса “Добавление отслеживания, калибровка, добавление курсора, регистрация жестов управления”. Однако простое название методов не могло полностью описать процесс, который вызовется, например, по вызову метода presentCalibration(), принимающий как параметр currentView. Поэтому к данному фреймворку были написаны 2 вида документации: "Пошаговое руководство по интеграции в документации компании", а также "Документация в публичных методах API", — которые описывают процессы, отрабатывающие после вызова метода. Например, далее приводится пример документации из руководства, описывающий работу калибровки и метода presentCalibration в частности:
1. вызывается метод presentCalibration();
2. генерирует CalibrateView, которое отслеживает сырые данные, получаемые от камеры, а также отображает ключевые точки на экране (грани и центр) для создания масштабирования плоскости проекции луча зрения на экран;
3. после калибровки первого уровня, указанной выше, запускает пространственную калибровку, суть которой в работе с проекцией взгляда при разных состояниях модели лица.
Как итог, калибровка занимала время. Не критичное, но пользователь мог не ожидать такого процесса, когда запускал калибровку. И с помощью простого описания метода не было возможности предупредить разработчика, чтобы уже он мог повлиять на пользовательский опыт и подготовить его к данному процессу. Однако документация описывала и процесс (не углубляясь в его внутреннюю работу и фокусируясь на пользовательском опыте), и последовательность действий для разработчика (should be called after...), ввиду чего интеграция сводилась к 4 вызовам и тому улучшению пользовательского опыта, который мы рекомендовали (как пример: перед началом калибровки выдавалось уведомление, что процесс займёт от 5 до 10 минут).
Итак, подведу небольшой итог.
Чем крупнее ваш проект, тем тяжелее разобраться в том, что делают те или иные компоненты. Однако документация может сильно сократить время, которое разработчики тратят на то, чтобы понять задачи компонентов и условия их работы. Поэтому хоть это и трудная работа, но она необходима, ведь за те полчаса, что вы потратите на описание нового компонента, остальная команда сэкономит дни или может недели.
