Делай как вGoogle
 Скачать 5.77 Mb.
|
Большинство современных языков программирования являются объектно-ориен- тированными. Поэтому комментарии к классам важны для определения «объектов» Виды документации 195 API в кодовой базе. Все общедоступные классы (и структуры) в Google должны сопровождаться комментарием к классу, описывающему класс (структуру), основ- ные методы и назначение класса (структуры). Как правило, комментарии к классам должны подчеркивать их объектную сущность, например: «Класс Foo , содержащий x , y , z , позволяет выполнять такие-то действия и характеризуется следующими свойствами» и т. п. В общем случае комментарии к классам должны выглядеть примерно так: // ------------------------------------------------------------------------ // AlphaNum // ------------------------------------------------------------------------ // // Класс AlphaNum действует в роли основного типа параметра для StrCat() // и StrAppend() и обеспечивает эффективное преобразование числовых, // логических и шестнадцатеричных значений (через тип Hex) в строки. Комментарии к функциям В Google все свободные функции и общедоступные методы классов тоже должны сопровождаться комментариями, описывающими их назначение. Комментарии к функциям должны описывать их активное состояние и начинаться с глагола в изъ- явительном наклонении, указывающего, что делает функция и что она возвращает. В общем случае комментарии к функциям должны выглядеть примерно так: // StrCat() // // Объединяет заданные строки или числа без использования разделителя, // возвращает результат объединения в виде строки. Обратите внимание, что начальный глагол в комментарии к функции обеспечивает согласованность заголовочного файла. Целеустремленные искатели могут быстро пробежать взглядом по API и прочитать только глаголы, чтобы понять, подходит ли им та или иная функция: «объединяет, удаляет, создает» и т. д. Некоторые стили документирования (и некоторые генераторы документации) требуют наличия в комментариях к функциям различных шаблонов, таких как «Returns:» (возвращает), «Throws:» (генерирует) и т. д., но мы в Google не считаем их строго необходимыми. Часто такую информацию лучше представить в свободной форме, не разбивая комментарий на разделы: // Создает новую запись с информацией о клиенте, используя заданные имя // и адрес, и возвращает числовой идентификатор записи или генерирует // исключение `DuplicateEntryError`, если запись для клиента с именем name // уже существует. int AddCustomer(string name, string address); Обратите внимание, насколько естественно выглядит совместное (в данном случае в одном предложении) описание постусловия, параметров, возвращаемого значения 196 Глава 10. Документация и исключительных случаев. Добавление явных шаблонных разделов сделало бы комментарий более многословным и повторяющимся, но не более (и, возможно, даже менее) ясным. Проектная документация Для начала работы над крупным проектом большинство команд в Google должны иметь одобренный проектный документ. Обычно проектные документы пишутся с использованием шаблона, утвержденного командой. Они предназначены для совместной работы и поэтому часто публикуются в Google Docs, где есть удобные инструменты для сотрудничества. Некоторые команды требуют, чтобы проектные документы рассматривались и обсуждались на общих совещаниях, где эксперты могли бы подвергнуть критике наиболее важные аспекты проекта. Предварительное обсуждение проекта действует как своеобразная форма обзора перед написанием кода. Поскольку разработка проектной документации осуществляется перед разверты- ванием новых систем, она подходит для очерчивания круга задач. Канонические шаблоны проектных документов в Google требуют включить в описание будущего проекта такие его аспекты, как безопасность, интернационализация, требования к хранилищу, конфиденциальность и т. д. В большинстве случаев эти аспекты рас- сматривают эксперты в соответствующих областях. Хороший проектный документ должен описывать цели проекта, стратегию его реализации и предлагать ключевые проектные решения с акцентом на конкретные компромиссы. Лучший проектный документ должен также охватывать альтернатив- ные проектные решения и обозначать их сильные и слабые стороны. После утверждения хороший проектный документ действует не только как хроно- логическая запись, но и как мера успеха в достижении поставленных целей. Боль- шинство команд сохраняют проектные документы вместе с остальными своими документами, чтобы иметь возможность периодически заглядывать в них. Часто бывает полезно пересмотреть проектную документацию перед выпуском продукта, чтобы убедиться, что цели, заявленные в проектном документе, актуальны (а если это не так, то документ или продукт можно соответствующим образом скоррек- тировать). Туториалы Каждый инженер-программист, присоединяясь к новой команде, должен как можно быстрее войти в курс дела. Наличие туториала (учебного руководства), помогающего настроить новый проект, неоценимо. Написание программы «Hello World» — это один из лучших способов взять удачный старт в новом деле. Это касается не только документов, но и кода. Большинство проектов стоит начать с создания документа «Hello World», который ничего не предполагает и помогает инженеру сделать что-то «реальное». Виды документации 197 Часто лучшее время для создания учебного руководства, если его пока нет, — период знакомства с новой командой. (Это также лучшее время для поиска ошибок в суще- ствующем учебном руководстве, которое вы читаете.) Откройте блокнот (или другой инструмент для заметок) и запишите все шаги, которые нужно выполнить для входа в курс дела, не имея знания предметной области или специальных ограничений. За- кончив этот список, вы поймете, какие ошибки допускали и почему, а затем сможете отредактировать свои записи, чтобы сформулировать последовательное учебное руководство. Обязательно описывайте все, что вам пришлось сделать, когда вы еще не знали конкретные настройки, разрешения или особенности предметной области. Если для старта вам были нужны определенные настройки, четко опишите их в на- чале руководства в виде набора предварительных условий. Если учебное руководство требует выполнения нескольких шагов в определенном порядке, пронумеруйте эти шаги. В руководстве, ориентированном на пользова- теля (например, внешнего разработчика), нумеруйте каждое действие, которое пользователь должен выполнить сам. Не нумеруйте действия, которыми система отвечает на действия пользователя. Явная нумерация шагов играет важную роль. Ничто так не раздражает, как ошибка на шаге 4 из-за неправильной авторизации. Пример: плохой туториал 1. Загрузите пакет с нашего сервера: http://example.com 2. Скопируйте сценарий командной оболочки в свой домашний каталог. 3. Запустите сценарий. 4. Система foobar соединится с системой аутентификации. 5. После аутентификации foobar создаст новую базу данных с именем baz 6. Протестируйте baz , выполнив команду SQL в командной строке. 7. Введите: CREATE DATABASE my_foobar_db; В предыдущей процедуре шаги 4 и 5 выполняются на стороне сервера. Нужно ли пользователю что-либо делать — неясно, в данном случае никаких действий со сто- роны пользователя не требуется, поэтому такие побочные эффекты лучше упомянуть в описании шага 3. Также неясно, являются ли шаги 6 и 7 разными действиями. (Здесь это не так.) Объедините все элементарные пользовательские операции в один шаг, чтобы пользователь знал, что делать на каждом этапе процесса. Кроме того, если ваше учебное руководство предлагает пользователю что-то ввести или проверить какой-то вывод, поместите команды и примеры вывода в отдельные строки (напри- мер, используя соглашение об оформлении моноширинным жирным шрифтом ). Пример: улучшенная версия плохого туториала 1. Загрузите пакет с нашего сервера: http://example.com : $ curl -I http://example.com 2. Скопируйте сценарий командной оболочки в свой домашний каталог: $ cp foobar.sh 198 Глава 10. Документация 3. Запустите сценарий в своем домашнем каталоге: $ cd ; foobar.sh Система foobar соединится с системой аутентификации. Затем foobar создаст новую базу данных с именем baz и откроет оболочку для ввода команд. 4. Протестируйте baz , выполнив команду SQL в командной строке: baz:$ CREATE DATABASE my_foobar_db; Обратите внимание, что каждый шаг требует конкретных действий со стороны поль- зователя. Если туториал фокусируется на каком-то другом аспекте (как, например, документ с описанием «жизненного цикла сервера»), пронумеруйте шаги с точки зрения этого аспекта (перечислите, что делает сервер). Концептуальная документация Иногда требуется дать более глубокое описание кода, которое нельзя получить из обычной справочной документации. В таких случаях мы пишем концептуальную документацию, в которой даем обзор API или систем. Примерами концептуальной до- кументации могут служить обзор API популярной библиотеки, описание жизненного цикла данных на сервере и т. д. Практически во всех случаях цель концептуального документа — дополнять, а не заменять справочную документацию. Часто это приво- дит к дублированию некоторой информации, но с важной целью: повысить ясность. В концептуальном документе необязательно охватывать все худшие случаи (но они обязательно должны быть перечислены в справочной документации). Здесь можно пожертвовать точностью ради ясности. «Концептуальные» документы являются наиболее сложными документами для написания, поэтому инженеры-программисты часто пренебрегают ими. Эти до- кументы невозможно встроить непосредственно в исходный код из-за отсутствия канонического места для них. Наиболее подходящим местом для «концептуального» объяснения обширного API является начальный комментарий в файле. Но неред- ко API используют другие API и/или модули, и единственное логичное место для описания такого сложного поведения — отдельный концептуальный документ. Если сравнить документирование с тестированием, комментарии будут похожи на юнит- тесты, а концептуальные документы — на интеграционные тесты. Даже для узких API часто имеет смысл написать отдельный концептуальный до- кумент. Например, библиотека Abseil StrFormat охватывает множество концепций, которые должны понимать ее пользователи, и мы предоставляем документ с описа- нием концепции ее формата ( https://oreil.ly/TMwSj), доступный как внутри библиотеки, так и за ее пределами. Концептуальный документ приносит пользу самой широкой аудитории, от экспертов до новичков. Кроме того, он должен делать упор на ясность, поэтому для его создания нередко приходится жертвовать полнотой сведений (описанных в справочной до- Обзоры документации 199 кументации) и (иногда) их точностью. Это не значит, что концептуальный документ должен быть намеренно неточным, но основное внимание в нем должно уделяться типичному использованию кода, а побочные эффекты лучше описать в справочной документации. Домашние страницы Большинство инженеров являются членами команд, и у большинства команд есть свои «домашние страницы» где-то в интранете компании. Часто эти страницы за- путаны: типичная домашняя страница может содержать несколько интересных ссы- лок, иногда несколько документов под названием «Сначала прочтите это!», а также некоторую информацию для команды и ее клиентов. Такие документы, первона- чально полезные, быстро превращаются в одно сплошное бедствие; они постепенно становятся слишком громоздкими, устаревают, и за их исправление берутся только самые смелые или отчаянные. К счастью, такие документы только выглядят пугающие, но на самом деле их легко исправить: убедитесь, что домашняя страница четко сообщает о своем назначении, и оставьте на ней только ссылки на другие страницы с более подробной инфор- мацией. Если домашняя страница выполняет какие-то дополнительные функции кроме регулировки движения, то она явно выполняет не свою работу. Если у вас есть отдельный документ с описанием установки, добавьте в домашнюю страницу ссылку на него. Если на домашней странице окажется слишком много ссылок (до- машняя страница не должна прокручиваться на несколько экранов), подумайте об их классификации. Часто домашняя страница служит двум разным целям: играет роль страницы «пере- хода» для тех, кто пользуется вашим продуктом или API, и является домашней страницей для команды. Не позволяйте странице обслуживать двух хозяев — это может сбить с толку. Создайте отдельную внутреннюю «страницу для команды» и от- дельную главную домашнюю страницу. То, что нужно знать команде, часто сильно отличается от того, что нужно знать пользователю API. Обзоры документации В Google весь код подвергается рецензированию, и наш процесс обзора кода вам уже понятен. В общем случае документация также нуждается в рецензировании (хотя это не общепринятый подход). Чтобы «проверить» качество вашей документации, отправьте ее на обзор. Технические документы подвергаются обзорам трех типов, каждый из которых пре- следует свои цели: y Технический обзор для проверки точности обычно проводится экспертами в предметной области или другими членами вашей команды часто в ходе обзора кода. 200 Глава 10. Документация y Обзор с позиции аудитории для проверки ясности проводится лицами, незнако- мыми с предметной областью, — новичками в вашей команде или пользователями вашего API. y Проверка орфографии и редактура проводятся техническими писателями или волонтерами. ПРИМЕР: РУКОВОДСТВО РАЗРАБОТЧИКА БИБЛИОТЕКИ Как упоминалось выше, мы столкнулись с проблемами, обусловленными тем, что большая часть (почти вся) технической документации находилась в общей электронной энцикло- педии (Wiki). Среди них — отсутствие четко обозначенных владельцев, конкурирующая документация, устаревшая информация и трудности с регистрацией ошибок. Но эти про- блемы не коснулись руководства по стилю для C++, потому что арбитры стиля взяли на себя заботу о нем. Их владение документом принималось безоговорочно. Кроме того, документ был каноническим: в Google существовало только одно руководство по стилю для C++. Как уже отмечалось, если документация находится рядом с исходным кодом, она обычно является наиболее авторитетной (надеюсь) и становится канонической. В Google каждый API обычно имеет отдельный каталог g3doc, в котором находятся канонические докумен- ты (в виде файлов в формате Markdown, доступных для чтения в нашем браузере Code Search). Размещение документации рядом с исходным кодом не только устанавливает фактическое владение, но и делает документацию «частью» кода. Однако размещение некоторых наборов документов в исходном коде выглядит нелогично. Например, для «Руководства разработчика на C++», созданного в Google, нет очевидного места в исходном коде. Нет и главного каталога «C++». В таких случаях (и если докумен- тация выходит за рамки одного API) мы стали создавать отдельные наборы документов. Многие из них объединяли существующие документы в общий набор с общей навигацией и общим внешним видом. Такие документы маркировались как «Руководство разработ- чика» и, так же как код в кодовой базе, сохранялись в VCS, в специальном разделе для до- кументации, причем этот раздел был организован по темам, а не по API. Поддержкой этих руководств для разработчиков в большинстве случаев занимались технические писатели, потому что они лучше справлялись с описанием тем, выходящих за рамки конкретных API. Со временем эти руководства для разработчиков стали каноническими. Пользователи, писавшие конкурирующие или дополняющие документы, начали стремиться добавлять свои документы в канонический набор, а затем отказываться от своих конкурирующих документов. В итоге руководство по стилю для C++ стало частью более крупного «Руко- водства разработчика на C++». Набор документации стал более полным и авторитетным, и его качество улучшилось. Инженеры начали сообщать об ошибках, потому что знали точно, что кто-то сопровождает эти документы. А поскольку документы хранились в VCS и имели конкретных владельцев, инженеры также начали отправлять списки изменений непосредственно техническим писателям. Внедрение ссылок go/ (глава 3) упростило выделение каноничных документов по разным темам. Например, наше «Руководство разработчика на C++» было опубликовано под ссылкой go/cpp . Благодаря улучшенному внутреннему поиску, ссылкам go/ и объединению документов наборы канонической документации со временем стали еще более авторитет- ными и надежными. Философия документирования 201 Конечно, эти виды обзоров имеют довольно размытые границы, но если ваш до- кумент предназначен для широкой аудитории или может публиковаться за преде- лами организации, то вы наверняка захотите подвергнуть его как можно более разносторонней оценке. (Аналогичный процесс обзора мы использовали для этой книги.) Вышеупомянутые виды обзора полезны для оценки даже узкоспециальных документов. Но если ваш текст оценит всего один рецензент, это все равно лучше, чем отсутствие рецензии. Важно отметить, что если документация связана с технологическим процессом, ее нужно улучшать со временем. Большинство документов в Google неявно проходят обзор с позиции аудитории, когда читатели кода находят в них ошибки и дают об- ратную связь (с использованием разных инструментов). Философия документирования Внимание: следующий раздел — это скорее рассуждение (и личное мнение) о луч- ших методах написания технических документов, а не описание «как это делается в Google». Понимание представленных идей, вероятно, поможет вам писать техни- ческую документацию. Кто, что, когда, где и почему Большинство технических документов отвечают на вопрос КАК. Как это работает? Как использовать этот API? Как настроить этот сервер? В результате инженеры-про- граммисты склонны сразу переходить к разделу КАК в документе и игнорировать другие вопросы: КТО, ЧТО, КОГДА, ГДЕ и ПОЧЕМУ. Да, они не так важны, как вопрос КАК. Исключением является только проектный документ, потому что он в большей степени посвящен ответу на вопрос ПОЧЕМУ. Но без надлежащей ор- ганизации технические документы приводят к путанице. Попробуйте ответить на другие вопросы, кроме КАК, в первых двух абзацах документа: y КТО, как обсуждалось выше, — это аудитория документа. Иногда желательно обозначить ее явно, например: «Этот документ предназначен для новых инже- неров проекта Secret Wizard». y ЧТО определяет назначение документа: «Этот документ является руководством по запуску сервера Frobber в среде тестирования». Иногда раздел ЧТО помогает правильно оформить документ. Информацию, не применимую к ЧТО, вы сможете переместить в отдельный документ. y КОГДА определяет дату создания, пересмотра или обновления документа. Доку- менты в исходном коде датируются неявно, а некоторые другие схемы публикации автоматически добавляют дату. Обязательно укажите в самом документе, когда он был написан (или пересмотрен в последний раз). y ГДЕ — это место хранения документа, которое часто подразумевается автором не- явно. Обычно предпочтительнее использовать VCS, в идеале — рядом с исходным |