Делай как вGoogle
 Скачать 5.77 Mb.
|
|
Документация как код Инженеры-программисты, которые пишут на одном основном языке программирова- ния, все еще часто используют другие языки для решения узких задач. Инженер может писать сценарии на языке командной оболочки, а для выполнения некоторых задач в командной строке использовать Python или писать большую часть внутреннего кода на C++, а интерфейсную часть — на Java и т. д. Каждый язык — это инструмент в наборе. Документация — это тоже инструмент, написанный на другом языке (обычно на английском) для решения конкретной задачи. Написание документации мало чем отличается от написания кода. Как и программирование, этот процесс управляется своими правилами, особым синтаксисом и соглашениями по стилю. Цель докумен- тации подобна той, что преследует код: обеспечить согласованность, повысить яс- ность и избежать ошибок. Грамматика в технической документации стандартизирует изложение и предотвращает путаницу в изложенных сведениях. По этой причине Google требует придерживаться определенного стиля в комментариях. Документация как код 189 ПРИМЕР: ЭЛЕКТРОННАЯ ЭНЦИКЛОПЕДИЯ GOOGLE Когда компания Google была намного меньше, в ней было мало технических писателей. В ту пору самым простым способом поделиться информацией была внутренняя электрон- ная энциклопедия GooWiki. Сначала она казалась разумным подходом: все инженеры пользовались одним комплектом документации и могли обновлять ее при необходимости. Но по мере роста Google проблемы с GooWiki становились все очевиднее. В отсутствие на- стоящих владельцев многие документы устарели 1 . Без четкого процесса добавления новых документов начали появляться дубликаты. Пространство имен в GooWiki было плоским, поэтому ни о какой иерархии в наборах документов не было и речи. Мы нашли в GooWiki от семи до десяти документов (по разным подсчетам) с описанием настройки Borg — нашей производственной вычислительной среды. Только некоторые из них продолжали поддер- живаться, а большинство были специфичны для определенных групп. Со временем появилась еще одна проблема: исправлять документы в GooWiki могли не те, кто их использовал. Новые пользователи, обнаружившие ошибки в документах, либо не могли подтвердить их, либо не имели возможности сообщить о них. И наоборот, авторам, которые могли бы внести исправления, часто не требовалось работать с документами после их написания. Постепенно документация ухудшилась настолько, что ее низкое качество стало все чаще отмечаться в ежегодных опросах разработчиков Google. Одно из решений, способствовавших улучшению документации, состояло в перемещении важной документации в VCS, аналогичную системе для хранения кода. Документы при- обрели владельцев, каноническое местоположение в дереве исходного кода и процессы выявления и исправления ошибок. Благодаря этим мерам документация начала резко улуч- шаться. Кроме того, процессы написания и поддержки документации стали более похожими на процессы написания и поддержки кода. Появилась возможность сообщать о найденных в документах ошибках в программе отслеживания ошибок и вносить изменения в документы в процессе обзора кода. В конце концов, инженеры начали сами исправлять документы или посылать изменения техническим писателям (которые часто были владельцами). На первом этапе перемещение документации в VCS столкнулось с рядом противоречий. Многие инженеры были убеждены, что отказ от GooWiki, этого бастиона свободы ин- формации, приведет к снижению качества документов из-за повышенных требований к ним (требований к проведению обзоров, наличию владельцев и т. д.). Но на самом деле документы стали только лучше. Также помогло внедрение Markdown в роли общепринятого языка разметки для оформле- ния документации, благодаря которому инженеры быстро освоили приемы редактирова- ния документов без специальных знаний HTML и CSS. В итоге Google представила свой фреймворк для встраивания документации в код: g3doc ( https://oreil.ly/YjrTD ), который способствовал дальнейшему улучшению качества документации, находящейся рядом с ис- ходным кодом в среде разработки. Теперь инженеры могут обновлять код и связанную с ним документацию в одном изменении (мы продолжаем попытки распространить эту практику). Главный прорыв состоит в том, что поддержка документации стала больше походить на поддержку кода: инженеры выявляют ошибки в документах, вносят изменения, отправляют их экспертам для обзора и т. д. Ключевым преимуществом выбранного подхода стало ис- пользование существующих рабочих процессов вместо создания новых. 1 Отказавшись от GooWiki, мы обнаружили, что около 90 % документов не обновлялось и не пересматривалось в течение многих месяцев. 190 Глава 10. Документация Документы, так же как код, должны иметь владельцев. Документы без владельцев становятся устаревшими и сложными в сопровождении. Чем более ясно выражено владение, тем проще обрабатывать документацию с использованием существующих рабочих процессов: систем отслеживания ошибок, инструментов обзора кода и т. д. Конечно, документы, принадлежащие разным владельцам, могут конфликтовать друг с другом. В этих случаях важно определить каноническую документацию: найти главный источник и объединить в него другие связанные документы (или исключить дубликаты). Документы с прямыми ссылками go/ (глава 3) часто становятся каноническим ис- точником информации. Еще один способ выделения канонических документов — их размещение в VCS и рядом с соответствующим исходным кодом. Документация часто тесно связана с кодом и рассматривается как код ( https://oreil. ly/G0LBo ). Она должна: y подчиняться внутренним правилам; y храниться в VCS; y иметь ясно обозначенных владельцев, ответственных за ее сопровождение и под- держку; y подвергаться обзорам в случае изменения (и изменяться вместе с кодом, который она описывает); y как и код, отражаться в системе отслеживания ошибок; y периодически переоцениваться (подвергаться своего рода тестированию); y оцениваться на точность, актуальность и т. д. (эта сфера остается неохваченной инструментами). Чем чаще инженеры будут рассматривать документацию как «одну из» обязательных задач разработки ПО, тем меньше они будут возмущаться необходимостью тратить время и силы на ее написание и тем весомее будут долгосрочные выгоды от доку- ментирования. Кроме того, упрощение процесса документирования может помочь снизить первоначальные затраты на него. Знание своей аудитории Одна из главных ошибок при написании документации — документировать только для себя. Это естественное стремление, и написание для себя тоже несет определенную пользу: в конце концов, вам может понадобиться заглянуть в код через несколько лет и понять, что вы имели в виду, когда его писали. Конечно, читающие ваш до- кумент могут иметь примерно тот же уровень знаний и навыков, что и вы. Но если писать только для себя, вы неизбежно будете основываться на определенных пред- положениях, а к вашему документу, возможно, будет обращаться очень широкая аудитория (все инженеры, внешние разработчики), и потеря даже нескольких чита- телей — это большие затраты. По мере роста организации ошибки в документации будут становиться более заметными, а ваши предположения — более ошибочными. Знание своей аудитории 191 Поэтому, прежде чем начать писать, вы должны (формально или неформально) опре- делить аудиторию документа. Проектный документ в первую очередь предназначен для представления доказательств лицам, принимающим решения. Учебное пособие должно содержать четкие инструкции для тех, кто совершенно не знаком с вашей базой кода. В описании API может потребоваться предоставить полную и точную справочную информацию для любых пользователей этого API, будь то эксперты или новички. Всегда старайтесь определить основную аудиторию и пишите для нее. Хорошая документация не должна быть «идеальной». Часто инженеры ошибочно предполагают, что они должны в совершенстве владеть навыками технического писателя. Однако мало кто из инженеров-программистов способен писать докумен- тацию на таком уровне. Подходите к написанию документации как к тестированию или любому другому процессу — то есть как инженер. Пишите текст, используя слог и стиль, ожидаемые вашей аудиторией. Если вы умеете читать документы, то сможете их написать. Помните, что вы тоже когда-то находились в вашей аудитории, только без сегодняшних знаний в предметной области. Поэтому от вас не требуется быть великим писателем; вы просто должны познакомить читателя с предметной областью. (И пока вы отвечаете за свою документацию, вы можете улучшать ее.) Виды аудиторий Как отмечалось выше, ваши документы должны соответствовать уровню навыков и знаний аудитории. Но кто относится к аудитории? Скорее всего, у документа будет несколько аудиторий, разделенных по следующим критериям: y уровень опыта (опытные программисты или младшие инженеры, которые могут даже не знать — внимание! — языка); y уровень знания предметной области (члены команды или другие инженеры в ор- ганизации, которые знакомы только с конечными точками API); y цель (конечные пользователи, которым нужен ваш API для решения конкретной задачи, желающие быстро найти информацию, или программисты-гуру, отвеча- ющие за внутреннюю реализацию, которую, по вашему мнению, больше никому не придется поддерживать). Иногда для разных аудиторий документация должна быть написана в разных стилях, но в большинстве случаев документация должна быть настолько универсальной, насколько это возможно. Часто вам придется объяснять сложную тему и экспер- там, и новичкам. Описывая предметную область для эксперта, хорошо знающего ее, вы можете позволить себе срезать некоторые углы, но тогда вы запутаете новичка. И наоборот, подробное объяснение, написанное для новичка, несомненно будет раздражать эксперта. Очевидно, что документирование связано с постоянным поиском баланса, и эта проблема не имеет универсального решения, но мы уверены, что такой подход по- могает сократить документы. Пишите достаточно наглядно, объясняя сложные темы 192 Глава 10. Документация людям, незнакомым с ними, но не отталкивайте и не раздражайте экспертов. Чтобы написать короткий документ, часто требуется сначала написать более длинный (из- ложив в нем все сведения), а затем выполнить редактирование и удалить повторяю- щуюся информацию везде, где возможно. Это может показаться утомительным, но имейте в виду, что эти усилия распространяются на всех читателей документации. Как однажды сказал Блез Паскаль, «если бы у меня было больше времени, то я бы написал короче». Стараясь сохранить документ как можно более коротким и ясным, вы сможете гарантировать, что он удовлетворит как эксперта, так и новичка. Не менее важно уметь различать аудиторию, основываясь на том, как пользователь применит документ. y Целеустремленные искатели — это инженеры, которые знают, чего хотят, и для них важно, чтобы документ отвечал их потребностям. Ключевым приемом при создании документации для этой аудитории является последовательность. Если вы пишете справочную документацию для этой аудитории — например, в файле кода, — ваши комментарии должны следовать формату справочника, чтобы чита- тели могли быстро просмотреть их и определить, есть ли в них искомые сведения. y Наткнувшиеся случайно могут не знать точно, чего они хотят. Они могут иметь лишь смутное представление о том, как реализовать необходимое. Ключ к этой аудитории — ясность. Добавьте в документацию общий обзор или вводную часть (например, в начале файла) с объяснением назначения кода, который они просматривают. Также полезно указать, для какой аудитории документ не подходит. Многие документы в Google начинаются с «аннотации», например: «Аннотация: если вас не интересуют компиляторы C++ в Google, можете дальше не читать». Наконец, учитывайте разницу между потребителем (например, пользователем API) и производителем (например, членом команды проекта) — по возможности доку- менты, предназначенные для одной аудитории, должны отличаться от документов, предназначенных для другой. Детали реализации важны членам команды для успеш- ного сопровождения, а конечным пользователям не нужна эта информация. Часто инженеры включают проектные решения в справочник по API своей библиотеки. Описание таких решений более уместно в конкретных (проектных) документах или, в лучшем случае, внутри реализации, скрытой за интерфейсом. Виды документации В процессе работы инженеры пишут разные виды документации: проектные до- кументы, комментарии в коде, инструкции и многое другое. Все это считается «документацией». Но важно знать разные виды документации и не смешивать их. Документ должен иметь, как правило, одну цель и придерживаться ее. Так же как в API, который должен делать что-то одно и делать это хорошо, не пытайтесь со- вместить все и вся в одном документе. Разбейте информацию на логические части. Виды документации 193 Существует несколько основных видов документов, которые часто приходится писать инженерам-программистам: y справочная документация, включая комментарии в коде; y проектные документы; y учебные руководства; y концептуальная документация; y посадочные страницы. В первые годы существования Google для нас было обычным делом создавать монолитные wiki-страницы с множеством ссылок (многие из которых оказывались неработающими или устаревали со временем), концептуальной информацией о си- стеме, справкой по API и т. д. Такие документы были очень неудобны, потому что не служили ни одной цели (и были настолько длинными, что их никто не хотел читать; некоторые из них занимали до нескольких десятков экранов). Не повторяйте наших ошибок, пишите документ, преследующий одну цель, и если информация, добавля- емая на страницу, не связана с ней по смыслу, подберите для нее другой документ или даже создайте новый. Справочная документация Справочная документация — это наиболее распространенный вид документации, которую приходится писать инженерам почти каждый день. К ней относятся все до- кументы, описывающие порядок использования кода. Комментарии в коде — самая распространенная форма справочной документации, которую должен вести инженер. Их можно разделить на две основные категории: комментарии с описанием API и комментарии с описанием реализации. Помните о различиях между аудиториями этих двух категорий. Комментарии с описанием API не должны обсуждать детали реализации или проектные решения и не могут предполагать, что пользователь разбирается в API настолько же хорошо, как и автор. Комментарии с описанием реализации, напротив, могут предполагать наличие у читателя глубоких знаний предметной области, но будьте осторожны и не заходите слишком далеко в своих предположениях: вы можете покинуть проект, поэтому должны подробно описать, почему код написан именно так. Большая часть справочной документации, даже если она оформляется как отдель- ный документ, генерируется из комментариев внутри кодовой базы. (Желательно, чтобы справочная документация имела только один источник.) Некоторые языки программирования, такие как Java или Python, имеют специализированные фрейм- ворки для обработки комментариев (Javadoc, PyDoc, GoDoc), упрощающие создание справочной документации. Другие языки, такие как C++, не имеют стандартной реализации справочной документации, но поскольку C++ отделяет определение API (в заголовочных файлах .h ) от реализации (в файлах .cc ), заголовочные файлы часто являются естественным местом для описания API в C++. 194 Глава 10. Документация В Google широко используется такой подход, как размещение справочной документа- ции с описанием API на C++ в заголовочных файлах. В других языках, таких как Java, Python и Go, справочная документация встраивается непосредственно в исходный код. Браузер Google Code Search (глава 17) настолько надежен, что избавляет нас от необходимости генерировать отдельную справочную документацию. Пользователи Code Search не только с легкостью находят нужный код, часто им удается найти оригинальное определение в первых результатах поиска. Наличие документации в коде также облегчает ее поиск и сопровождение. Все мы знаем, насколько важны комментарии в коде для документирования API. Но что отличает «хорошие» комментарии? Выше в этой главе мы определили две основные аудитории справочной документации: целеустремленные искатели и поль- зователи, наткнувшиеся на документ случайно. Для первых важно, чтобы база кода была прокомментирована последовательно для быстрого поиска искомых сведений. Вторым важно наличие четкого определения назначения API, желательно в начале заголовочного файла. В следующих подразделах мы подробнее рассмотрим некоторые виды комментариев в коде. Далее представлены рекомендации документирования для C++, которые подходят и для других языков. Комментарии в начале файла В Google почти все файлы с исходным кодом должны начинаться с комментари- ев. (Некоторые заголовочные файлы, содержащие только одну вспомогательную функцию и т. д., могут отступать от этого стандарта.) Комментарии в начале файла должны начинаться примерно с такого заголовка: // ------------------------------------------------------------------------ // str_cat.h // ------------------------------------------------------------------------ // // Этот заголовочный файл содержит сигнатуры эффективных функций // для объединения строк: StrCat() и StrAppend(). Основная работа в этих // функциях выполняется с использованием типа AlphaNum, специально // разработанного как тип параметров, который эффективно управляет // преобразованием строк и позволяет избежать копирования // в вышеперечисленных операциях. Как правило, комментарий в начале файла должен начинаться с общего описания того, что содержится в коде, перечислять основные варианты использования кода и идентифицировать аудиторию (в данном случае это разработчики, желающие использовать инструменты объединения строк). Если API не получается кратко описать в одном-двух абзацах, это обычно является признаком плохо продуманного API. В таких случаях можно попробовать разбить API на отдельные компоненты. |