зачем нужна документация в программировании
Документация как код: шесть принципов программирования, которые помогут создавать документы, понятные каждому
Авторизуйтесь
Документация как код: шесть принципов программирования, которые помогут создавать документы, понятные каждому
Рассказывает Дмитрий Толоконников, бизнес-аналитик департамента ИТ-аутсорсинга ALP Group
Больше пяти лет я занимаюсь бизнес-процессами. В особенности процессами технической поддержки, которую мы оказываем коммерческим и государственным компаниям. Например, я слежу, чтобы уровень качества IT-обслуживания соответствовал международным стандартам. Я программирую и работаю с документацией — пишу регламенты и процедуры, описываю процессы, выпускаю инструкции.
Всё это время я неосознанно «перетаскиваю» общие принципы программирования в работу с документами. Это помогает мне не делать бесполезные «спагетти-простыни» и писать внятные рабочие документы с ясной структурой, даже если документация очень объёмная и должна часто меняться в соответствии с изменениями в компании и все её части должны быть связаны воедино, чётко объяснять, как что-то работает. Возможно, мои приёмы помогут и вам.
Принципы работы с текстом
DRY — Don’t repeat yourself. Не повторяйся
Если вы вставили один и тот же блок в 10 разных регламентов и что-то меняете в нём, то у вас образуется 10 одинаковых мест, куда нужно внести одинаковые изменения. Вероятность забыть об этом тоже растёт, даже если вы пользуетесь бессмертным «Ctrl+C» — «Ctrl+V». Особенно в последней паре документов.
В программировании такие блоки выделяют в отдельные функции, классы, а в работе с документами повторяющиеся элементы нужно выносить в отдельные разделы или документы и давать ссылки на них.
KISS — Keep it simple, stupid. Не усложняй
Посмотрите вокруг: люди привыкли к простоте. Интуитивно понятные интерфейсы и всплывающие подсказки в приложениях. Принцип одного окна в IT-обслуживании. Засилье коротких статей и обучающих видео в Интернете. Той же простоты они ждут и от рабочих документов.
12–14 ноября, Онлайн, Беcплатно
Этот принцип я обычно использую как маркер. Если описание процесса слишком сложное — нужно упростить процесс. Если инструкция к приложению слишком замысловатая — надо доработать приложение.
Обычно это проще и дешевле, чем писать сложную документацию, заставлять каждого нового сотрудника её читать, понимать и учиться действовать по ней. А ведь потом ещё нужно будет вносить изменения в документацию.
YAGNI — You ain’t gonna need it. Тебе это не понадобится
Это продолжение принципа KISS. Обычно я применяю его, когда собираюсь создать универсальное решение с заделом на будущее. Проблема в том, что такое решение — само по себе усложнение. Не факт, что в будущем оно понадобится. Обычно нет смысла создавать всеобъемлющее описание бизнес-процессов направления, которое только сформировалось и активно развивается. Практика показывает, что будущее внесёт серьёзные коррективы.
Но здесь важно разумно подходить к вопросу. Есть вещи, изменение которых дорого обходится. Их как раз нужно готовить с заделом на будущее. В программировании эту работу относят к архитектуре приложения, а в документации просто сразу говорят: «Это нам не понадобится». И в будущем с трудом навёрстывают упущенное.
Принципы работы со структурой
Чем объёмнее становится документация, тем сложнее поддерживать её актуальность. Изменение одного документа влечёт за собой каскадное изменение остальных, логическая целостность ломается, структура требует очередной переработки. К счастью, для программирования это стандартная проблема, и за прошедшие десятилетия выработались общие принципы написания легко поддерживаемого кода. Часть из них можно применять и к документам.
SRP — Single Responsibility Principle. Принцип единственной ответственности
Яркий маркер нарушения принципа — наличие побочных действий. Например, метод класса отвечает за отправку клиенту уведомления о новом заказе в интернет-магазине, но при этом ещё и обновляет текущий баланс клиента.
То же самое справедливо и для документации. Например, в регламент регистрации обращения клиента не нужно впихивать что-то «заодно»: принципы вежливого общения с клиентами, краткое описание self-service портала и т. д.
Нельзя рассчитывать, что такая информация будет усвоена или сотрудники запомнят, к какому документу нужно обращаться, чтобы её получить. Зато это запутывает документ, лишает структуру чёткости и требует дополнительного времени для актуализации. Если вы действительно хотите напомнить о вежливости при общении с клиентом, вставьте в регламент ссылку на соответствующий документ (вспомните о DRY).
Соблюдение принципа позволяет делать документы короче. Их название соответствует назначению, а чтение не вызывает неприятных сюрпризов. Их проще прочитать за раз. И не забыть, с чего документ начинался.
SLAP — Single Level of Abstraction Principle. Принцип единого уровня абстракции
Является логичным продолжением принципа единственной ответственности (SRP).
Применение принципов KISS и SRP побуждает писать небольшие, простые и понятные документы. Но эти документы нужно собрать в такую же простую и понятную структуру. Здесь помогает выделение и соблюдение уровней абстракций.
Например, очевидно, что нет смысла пытаться поместить в один огромный документ объёмную документацию вроде описания системы менеджмента качества. Намного логичнее разбить его на уровни абстракций и сделать для каждого уровня разные документы — верхнеуровневое описание системы, описание каждого процесса и т. д.
При этом важно соблюдать принцип единого уровня абстракций и относить информацию только к нужному уровню. Если вы пишете верхнеуровневое описание, не надо вдаваться в детали работы конкретного процесса. Не тот уровень абстракции! Оставьте эту информацию для описания процесса. Этот принцип дополняет SRP, заставляя автора контролировать не только то, за что отвечает документ, но и на каком уровне в иерархии он находится.
LoD — Law of Demeter (Don’t talk to strangers). Закон Деметры (Не разговаривай с незнакомцами)
Если применить закон к документации, то каждый документ:
Например, процесс управления IT-инцидентами взаимодействует с процессом управления проблемами напрямую, а с процессом управления изменениями — только через управление проблемами. Тогда в описании управления инцидентами можно ссылаться на описание управления проблемами. А вот ссылаться на описание управления изменениями не надо.
Итого
Указанные выше принципы сильно помогают мне при написании документации по процессам, в создании регламентов, процедур и инструкций. К сожалению, это лишь небольшая часть рекомендаций по управлению качеством кода, поэтому заинтересовавшимся рекомендую самостоятельно углубиться в тему. Из неё можно извлечь много полезного. При этом важно помнить, что эти принципы не являются законами. В Интернете много спорят об их правильном использовании и часто злоупотребляют ими. Поэтому, пожалуйста, не впадайте в крайности. И не забывайте о здравом смысле.
Документирование кодовой базы. Зачем и как?
Введение
Недавно, на одном из митингов моей команды, была поднята проблема отсутствия документации внутри кода. Было решено назначить ответственного за ведение документации. Нужно было найти подходящие инструменты документирования, определить стиль и регламент, представить решение команде. Я решил, что возьму эту задачу на себя, так как для меня это особенно важный вопрос. Мне, как новому сотруднику, было довольно тяжело разобраться в уже существующем коде без документации, и упустить возможность повлиять на ее появление я просто не мог. В итоге, в процессе определения стандарта для нашей команды и появилась эта статья. Я подумал о том, здесь присутствуют довольно интересные мысли, поэтому решил поделиться ими здесь.
Дисклеймер
Так как я С++ разработчик, то и документирование кода я рассматриваю как документирование кода С++. Когда я говорю код, функция, метод или класс, я подразумеваю код, функцию, метод или класс на С++.
Зачем?
Здесь я приведу пару пунктов формата вопрос-ответ. Это те вопросы, которые я задавал себе сам и слышал от своих коллег, когда вставал вопрос документирования кода.
«Все и так знают наш код»
Это утверждение справедливо для разработчиков с большим опытом работы в компании, но никак не для тех, кто только включается в проект. Чем больше документации встретит новичок в коде, тем быстрее он сможет включиться в работу. 10 минут чтения документации лучше, чем 2 часа отладки кода.
«Этот код прост и не нуждается в документации»
Если такая мысль пришла вам в голову, обдумайте ее еще раз. Если подумать еще не помогло, посоветуйтесь со своими коллегами. Если ваш код не вызвал вопросов при одном только взгляде на него, то, возможно, комментирование кода действительно излишне (но это не точно). Этот пункт будет подробнее обсуждаться далее.
«Этим кодом больше никто пользоваться не будет»
Это неправда. Не использоваться он будет до поры до времени. В моей практике были моменты, когда я реализовывал то, что уже есть в нашей кодовой базе. Отсутствие документации и, соответственно, привычки искать существующие решения в ней, привели меня к дубликации кода.
Общие советы документирования
Приведите пример использования вашего кода
Оставьте названия функций/методов/классов, ткните в место, где используется ваш код. Если вы использовали какое-то популярное решение (паттерн), оставьте ссылку на материал по этой теме. Это поможет быстрее сориентироваться в коде. Понятно, что поиск в IDE даст вам ту же информацию, но иногда он бывает долгий, плюс таким образом вы сможете особенно выделить то место, где использование вашего кода продемонстрировано максимально явно.
Если решение нетривиально, расскажите о причинах такого решения
Почему использовано именно такое решение? Порой приходится много времени заниматься отладкой и изучением кода, чтобы понять, почему коллега выбрал именно такой подход. Краткий ответ на вопросы зачем и почему сэкономит много времени. Данный пункт переплетается с первым.
Постарайтесь найти середину между отсутствием документации и документированием каждой строки
Не нужно писать целую поэму для метода, из названия которого понятно, что он делает (я надеюсь, что название соответствует тому, что он делает). Также не стоит думать, что, например, простой класс не нуждается в подробной документации. Здесь важно найти золотую середину.
Не пересказывайте код
Не превращайте ваши комментарии в это
Пример того, как делать не надо
Не забывайте о поддержке документации IDE
Сейчас почти все IDE способны выводить описание класса/метода/функции при взаимодействии с ним (наведение мыши, комбинация клавиш), если описание оформлено в нужном формате. Пишите документацию так, чтобы (1) IDE смогла ее «подхватить», (2) можно было обойтись чтением документации и избежать необходимости открывать код с целью его изучения.
Дайте описание поведения вашей функции/метода в случае ошибки
Что вернет ваш код? Возможны ли исключения и какие? Если функция бросает слишком много исключений, возможно не стоит перечислять их все.
Помните о том, что ваши комментарии в будущем будут читать другие люди, в том числе и вы
Не пишите документацию ради документации, пишите ее ради облегчения работы своей команды. Задайте себе вопрос: пойму ли я, что делает этот код, через месяц, посмотреть на комментарии? Для более честного ответа, попросите ответить на этот вопрос своих коллег.
Не забывайте об актуальности документации
Неактуальная информация уже неактуальна хуже ее отсутствия.
Вопросы о грамотности, удобстве, понятности документации и прочие популярные я опускаю с надеждой на то, что такие вещи для читателя само собой разумеющееся.
Документирование можно вести в стандарте JavaDoc. Это удобный формат, который знаком многим IDE и поддерживается Doxygenом. Плюсом для нас было то, что он уже частично используется в нашем проекте, и IDE, в которых мы работаем (CLion, QtCreator, VisualStudio) прямо поддерживают генерацию комментариев в этом стандарте и их отображение.
Далее будут описаны инструменты документации и некоторые правила, которые мы приняли в своей команде.
Многострочные и однострочные комментарии
Doxygen поддерживает много видов комментариев. Для нашей команды я выделил такие:
Хочу обратить внимание, что
Также существует такой вид комментария:
Такой вариант удобен, когда нужно задокументировать одну строку внутри функции, или дать описание переменной или члену класса/метода. Обратите внимание, что между слэшем и стрелкой нет пробела.
Команды
В JavaDoc есть так называемые команды. Команды служат для детализации, выделения документации. Команд в JavaDoc довольно много, плюс можно вводить свои. Те команды, которые используем мы, я опишу далее. К сожалению, многие команды (почти все) в C++ не поддерживаются так, как хотелось бы (так, как это сделано в Java). Но тем не менее это отличный способ структурировать вашу документацию, обеспечить удобство при чтении и поддержку Doxygen. Я настоятельно рекомендую пользоваться командами.
Классы, структуры, перечисления, области видимости
Документация должна находиться строго до объявления/описания кода. Это позволит нашим IDE, и в дальнейшем Doxygenу, подхватить комментарии.
Мы документируем такой код многострочным комментарием, даже если описание влезает в одну строку.
Это позволяет комментариям не выбиваться из общего стиля документирования. Комментарии в одну строку блочного кода должны быть редкостью!
Для указания краткого описания может быть использована команда @brief. Указанный после команды текст, вплоть до конца параграфа, будет относиться к краткому описанию, и для отделения от основного используется пустая строка.
Также можно (и даже нужно) добавлять команду @example. Такой вариант позволит быстрее найти пример использования кода.
Это отличный вариант соблюдения 2 пункта из советов.
Документация функций/методов
Функции и методы также должны документироваться строго над объявлением/описанием. Здесь я также выступаю за многострочные комментарии по тем же причинам, что и выше.
int sum(int a, int b)
Опишите поведение функции/метода в случае ошибки (что возвращает, какие исключения кидает). Для этого можно использовать команду @throw.
Документация членов в классе/структуре, переменных в функции, значений в перечислениях
Для таких объектов будет удобен такой стиль документации:
Или на крайний случай
Документируйте переменные однострочными комментариями, старайтесь уместить комментарий в одну строку. Там, где это невозможно, используйте многострочные комментарии.
Более подробно о технических деталях документации рассказано тут.
Как обеспечить качественную документацию?
Доверить ревью новичку даст два больших плюса:
В перспективе вы получите:
Подробную и качественную документацию
Более быстрый рост и включение в проект своих новых сотрудников
Резюме
Понятно, что все, о чем я рассказал выше, «хорошо только на бумаге». Вероятней всего, на практике вы столкнетесь с трудностями: негодование ваших коллег/сотрудников о «бесполезной» работе, «бедной» документации, несогласия о стиле. Но не мне вам говорить, что такие изменения никогда не даются легко:) Грамотный подход к решению вопроса документации в перспективе окупит себя.
Ссылки, которые помогли мне к подготовке данного материала:
Какая документация нужна вашему проекту и кто должен её писать
Привет! Меня зовут Катя, я руководитель команды технических писателей в Ozon. Сейчас нас 11 человек на три платформы: пользовательскую доку, описание API и внутренние весьма технические штуки.
Как раз когда разбирала внутренние доки, разговаривала с лидами других команд и кандидатами на наши вакансии, поняла, что есть некоторая путаница в головах: не всегда понятно, какие документы нужны и кто должен их составлять.
Поэтому рассказываю, какие документы мы используем в Ozon и как мы их создаём.
Маленький хинт на старте:
при работе над любым документом важно в самом начале понять, кто и при каких условиях будет его читать. Если ответить на эти вопросы, станет понятно, что и как надо описывать. А иногда и не описывать вовсе, а показывать 🙂
в каждом документе за скобки вынесены технические писатели — они должны помогать делать текст полезным и понятным, следить за консистентностью терминов и оформления.
Регламенты и политики
Аудитория: все сотрудники компании.
Цель: обеспечить совместимость процессов разных команд, уменьшить время на разработку велосипедов.
Участники: верхнеуровневые лиды, внутренний аудит.
В личном раю каждого перфекциониста все всё делают одинаково и правильно с первой попытки. Но в суровой реальности люди иногда проводят десятки встреч для выяснения, что правильнее использовать: camelCase или snake_case. Поэтому компании придумали (или поддержали) писать такие документы, в которых собраны общие рекомендации по ведению вообще всего.
Политики в общем описывают, что такое хорошо, а чего следует избегать. Как правило, они располагаются около онбордингов, чтобы новые сотрудники сразу пропитывались именно теми подходами, которые приняты в компании. Такие документы обязательно верифицируются топ-менеджментом: CTO, CPO, CEO и другими chief’ами.
Например, политика безопасности может рассказывать, почему в компании не принято использовать инструменты с открытым кодом, или почему нельзя использовать корпоративную сеть для скачивания торрентов.
Регламенты — дополнения к политикам с конкретными описаниями каких-то процессов, направленных на выполнение политик. Они пишутся руководителями направлений, часто всеми вместе, и живут рядом с политиками.
Это, например, описание выкатки фичи в прод, получения учётной записи для тестирования на контуре или любого другого процесса, единого внутри компании.
Важно не перестараться и не пытаться составить регламент настройки высоты стула, если это никак не влияет на цели и метрики продукта.
При написании регламентов и политик помните, что люди а) должны понимать, зачем они вообще написаны, и б) иметь возможность легко им следовать. Избегайте сложных конструкций вроде «Данная политика распространяется на лица, предполагающие наличие доступа к информационным системам. »
В моей первой команде техписателей мы иногда устраивали соревнование: надо было максимально усложнить предложение. Рекомендую, полезное упражнение на умение распознавать сложные конструкции. Но следите внимательно за местом практики, чтобы никто не подумал о реальном использовании соревновательных вариантов.
Архитектуры
Аудитория: лиды, разработчики.
Цель: уменьшить количество встреч с объяснениями, как это всё устроено, ускорить онбординг, выявить и ликвидировать проектные костыли.
Участники: лиды, руководители направлений.
Это та документация, где очень много схем с названиями модулей. Частая практика — перестать понимать как устроен проект, нанять техписателя или аналитика и посадить его описывать происходящее. Частая проблема при этом: не все держатели знаний готовы помогать документатору и отвечать на его вопросы.
Большинство проблем в процессах можно отловить, если внимательно слушать, о чём спрашивают сотрудники в первую неделю работы. И популярный вопрос для почесывания затылка — «А откуда мы берём эти данные?». В ответ на него хорошо бы подсунуть схему с большим заголовком «Как всё тут между собой работает», но обычно она существует только в коллективном разуме — и приходится писать в чаты, организовывать встречи или даже регулярные мероприятия на овермного специалистов.
Составление архитектурных документов любят поручать аналитикам, потому что надеются, что в процессе описания такой специалист выдаст море рекомендаций — и в компании наступит счастье. Но наступаются почему-то только грабли.
Продолжу рекомендовать нанять опытного техписателя — он, возможно, и не выдаст полный анализ системы с планом развития на годы вперёд, но точно найдёт слабые места, пока будет проводить интервью с держателями знаний. Дальше уже можете отправить его на курсы аналитиков и развивать себе архитектора, а для поддержания документации взять стажера или младшего специалиста. Но очень прошу не смешивать роли: люди-оркесты в компаниях, бесспорно, могут быть полезными кадрами, но в целом на рынке это создаёт путаницу и огромную отдельную боль.
Интеграции
Аудитория: внешние пользователи.
Цель: уменьшить время на настройку системы, увеличить количество пользователей.
Участники: разработчики, тестировщики.
Внешними пользователями могут быть и внутренние разработчики, если они ещё не изучили ваш модуль.
Под интеграционными документами понимаются вещи, которые объясняют как и зачем настраивать взаимодействие с продуктом.
Не самый обязательный документ, потому что часто информацию об интеграции можно достать из описания проекта, или же интеграция может быть дополненной архитектурой — дописываем требования к модулям и получаем интеграцию.
В обще виде для интеграционных документов характерны разделы:
что это вообще такое и какие профиты от интеграции,
какие требования есть у системы и какие нюансы стоит предусмотреть,
сама инструкция вида «установите этот пакет, проверьте эти зависомости, наслаждайтесь нашим модулем»,
типичные ошибки и раздел частых вопросов.
Не очень люблю частые вопросы, потому что это свалка вещей, которые не влезли в основные разделы и приучают пользователя не читать всё, а пробежаться только по ним. Это неплохо с точки зрения решения проблем документацией, но это воспитывает очередное «зачем читать доку, если можно потыкаться и потом почитать ошибки».
Онбординги
Аудитория: новые сотрудники, сотрудники после ротации или упустившие какие-то нюансы.
Цель: снизить нагрузку с наставника и поднять у новеньких уровень понимания происходящего.
Участники: конкретная команда.
Здесь важнее, мне кажется, рассказать о самом процессе.
Соберите всю документацию, которая есть у команды. Про то, какая это должна быть документация и как её лучше собирать тема для отдельной статьи 🙂 Обратите внимание на тип документов: что они описывают, а какие темы не покрывают вообще. Специально не говорю какие это должны быть темы, чтобы у вас включался процесс мозгоштурма и анализ специфики конкретной команды.
После первого анализа отправляйтесь на встречу с лидом — пусть он расскажет о команде и процессах. Записывайте, задавайте вопросы и записывайте свои вопросы — именно они должны стать основой нового онбординга.
Найдите последнего пришедшего в команду человека, попросите написать те вопросы, которые он задавал в свои первые недели, и сверьте со своими. Вы восхитительны — теперь у вас есть рыба и можно начинать готовить онбординг.
Но ваша работа закончится только после первого обученного по вашему онбордингу сотрудника. Вам нужно будет переговорить с новеньким и сказать, мол, это свежая дока, мне очень важно твоё мнение — запиши, пожалуйста, все вопросы, которые у тебя возникнут в первые дни, укажи на места (в документе и в процессах), где ты что-то не понял.
Важно помнить, что и у вас, и у лидов уже есть опыт работы в компании и понимание общих терминов, процессов, жаргонизмов. И, скорее всего, вы их никак не отловите, потому что уже к ним привыкли. Поэтому ваш главный помощник при написании онбордингов — новый человек.
Из своего опыта — даю писать онбординги либо новым техписателям, либо тем, кто не пересекался ещё с командой-заказчиком. Так получается найти действительно самые основные вопросы.
Свалки полезностей
Аудитория: все сотрудники.
Цель: давать точечные ответы, формировать основную базу знаний.
Участники: все сотрудники, часто и без техписателей.
Оно же «Архив», «Нечто», «Чёрная книжечка» и можете продолжить ряд в комментариях.
Велик соблазн просто закинуть эти статьи куда подальше и иногда кидать на них ссылку. Но, по мнению археологов, свалки — одни из ценнейших находок, потому что дают полную картину образа жизни исследуемого времени и народа. Противоречий не вижу, поэтому любую структуризацию, шаблоны и типовые документы рекомендую искать именно здесь.
Призываю воспринимать хаос и бардак в документе как возможность для его организации.
Важно только учитывать, что, если свалка появилась, значит, она решала какие-то проблемы — не забудьте эти проблемы найти и предусмотреть в новой структуре. Иначе новым, красивым и понятным, не будут пользоваться.
Резюме
Да, это не полный список. Я не рассказала про документации для API, SDK и про внешние пользовательские Помощи разных калибров. Но основные нужды внутри компании этот набор должен покрыть.
Чтобы организовать документацию внутри компании, учитывайте:
существующие документы — в них зарыты актуальные проблемы и процессы,
вопросы новых сотрудников — они помогут сформировать полную картину необходимых знаний,
межкомандные договорённости и процессы — они упрощают работу, но не всегда очевидны, поэтому их важно донести до всех заинтересованных,
людей, процессы и отношения внутри компании — простое навязывание и запреты никогда не работает, поэтому
не пытайтесь слепо использовать чужой опыт, анализируйте и внедряйте именно то, что актуально для решения именно ваших запросов — никто лучше вас не знает ваши условия и цели.
А чтобы повышать насмотренность и иметь возможность выбрать из множества подходов — подписывайтесь на Блог компании Ozon Tech 🙂 Мы уже готовим новые статьи про документацию и не только!