Делай как вGoogle
 Скачать 5.77 Mb.
|
|
Пишите хорошие описания к изменениям Описание должно сообщать тип изменения с краткой сводкой в первой же строке, которая действует подобно строке с темой в электронных письмах — ее видят инже- неры Google в сводке истории в инструменте Code Search (глава 17). В описании следует подробно рассказать, что и почему изменяется. Описание «Ис- правление ошибок» не поможет ни рецензенту, ни будущему «археологу». Если изменение содержит несколько более мелких связанных изменений, перечислите их в виде списка (желательно короткого). Описание является хронологической за- писью для изменения, и такие инструменты, как Code Search, позволят вам найти, кто и какую строку написал, в любом конкретном изменении в кодовой базе. Поиск и исследование исходного изменения часто помогают при исправлении ошибок. Описания — не единственное место, куда можно добавить документацию к измене- нию. При разработке общедоступного API вы едва ли захотите включить в общее описание детали реализации, но непременно сделайте это в фактической реализации, добавив соответствующие комментарии. Если рецензент не поймет вашу задумку, даже правильную, это будет означать, что вашему коду недостает структуры и/или более ясных комментариев. Если в процессе обзора кода будет принято новое ре- шение, обновите описание изменения или добавьте соответствующие комментарии в реализацию. Обзор кода — это не только набор действий, выполняемых сейчас, но и описание ваших действий для будущих читателей. Привлекайте к обзору минимальное число рецензентов Большинство обзоров кода в Google выполняются всего одним рецензентом 1 . По- скольку проверка корректности, пригодности для владельцев и удобочитаемости кода может производиться одним человеком, процесс обзора кода хорошо масштабируется в организациях, сопоставимых по размерам с Google. 1 Там же. 182 Глава 9. Код-ревью Многие инженеры в отрасли хотят получать дополнительные комментарии (и еди- нодушное одобрение) от группы инженеров. В конце концов, каждый дополни- тельный рецензент может привнести что-то свое в обзор кода. Но мы выяснили, что увеличение числа рецензентов приводит к уменьшению отдачи: самое важное одобрение — LGTM, и аналогичные одобрения добавляют к этой отметке не так уж много информации. Затраты на привлечение дополнительных рецензентов быстро перевешивают ценность их комментариев. Процесс обзора кода протекает оптимально, потому что мы доверяем нашим инже- нерам. Иногда бывает полезно привлечь к обзору конкретного изменения несколько человек, но даже тогда рецензенты должны сосредоточиться на разных аспектах одного и того же изменения. Автоматизируйте все, что только можно Обзор кода — это процесс с участием человека, но если в процессе есть этапы, которые можно автоматизировать, попробуйте это сделать. Изучите возможность автоматизации механических задач, и инвестиции в эту автоматизацию окупятся сторицей. Инструменты, используемые в Google в процессе обзора кода, позволяют авторам автоматически отправлять изменения и синхронизировать их в VCS после утверждения (обычно они применяются для наиболее простых изменений). Одним из самых важных технологических усовершенствований в области автомати- зации, сделанных за последние несколько лет, является автоматический статический анализ изменений (глава 20). Инструмент автоматизации обзора кода в Google избав- ляет авторов от необходимости вручную запускать тесты и применять инструменты форматирования и статического анализа — он автоматически выполняет большую часть механической работы в ходе так называемой предварительной проверки перед отправкой. Процедура предварительной проверки запускается, когда изменение впервые посылается рецензенту. Она может обнаружить ошибки и отклонить из- менения (и предотвратить отправку электронного письма рецензенту), а также предложить автору исправить найденные недочеты. Такая автоматизация не только ускоряет процесс обзора кода, но также позволяет рецензентам сосредоточиться на более важных задачах, чем форматирование. Виды обзоров кода Обзоры кода не похожи друг на друга! Разные виды обзоров кода требуют разного уровня внимания к различным аспектам. В Google изменения обычно попадают в одну (или несколько) из следующих групп: y разработка новой возможности; y изменение в поведении, улучшение и оптимизация; y исправление ошибок и откат к прежним версиям; y рефакторинг и крупномасштабные изменения. Виды обзоров кода 183 Обзоры кода новых возможностей Реже всего проводятся обзоры совершенно нового кода — так называемые обзоры с нуля. Самое важное для обзора с нуля — оценить, выдержит ли код проверку вре- менем и насколько легко его будет поддерживать, потому что с течением времени и при росте организации могут измениться предположения, на которых этот код основывается. Конечно, появление совершенно нового кода не должно вызывать удивления. Как упоминалось выше в этой главе, код — это ответственность, поэтому совершенно новый код должен, как правило, решать реальную проблему, а не просто представлять еще одну альтернативу. Мы в Google обычно требуем, чтобы новый код и/или проект подвергались обширной проверке контекста. Обзор кода — не лучшее пространство для обсуждения проектных решений, принятых в прошлом (и к тому же обзор кода совершенно не подходит для представления предлагаемого дизайна API). Чтобы гарантировать устойчивость кода, в ходе обзора с нуля необходимо убедиться, что API соответствует согласованному дизайну (а для этого может потребоваться пересмотреть проектную документацию), и полностью его протестировать, причем все конечные точки API должны быть охвачены некоторой формой юнит-тестиро- вания и все тесты должны завершаться неудачей при изменении предположений, сделанных в коде (глава 11). Код также должен иметь соответствующих владельцев (в одном из самых первых обзоров нового проекта часто исследуется единственный файл OWNERS для нового каталога), содержать достаточно подробные коммента- рии и при необходимости включать дополнительную документацию. Обзор с нуля может также потребовать включения проекта в систему непрерывной интеграции (глава 23). Обзоры изменений в поведении, улучшений и оптимизаций Большинство изменений в Google связаны с модификацией существующего кода. К ним относятся изменения конечных точек API, улучшения существующих реали- заций или оптимизация других факторов, таких как производительность. Подобные изменения являются основной работой большинства инженеров-программистов. По принципу обзора с нуля, сначала нужно узнать, необходимо ли изменение и улучшает ли оно существующий код. Один из лучших способов улучшить общее состояние кодовой базы — удаление мертвого или устаревшего кода. Любые изменения поведения должны обязательно включать исправления в со- ответствующие тесты, проверяющие любое новое поведение API. Дополнения к существующей реализации мы тестируем в системе непрерывной интеграции, чтобы убедиться, что изменения не нарушают базовые предположения существу- ющих тестов. Оптимизации должны гарантировать, что они не влияют на тесты, и, возможно, включать критерии производительности, чтобы рецензенты могли проверить их. Некоторые оптимизации могут также требовать наличия тестов производительности. 184 Глава 9. Код-ревью Обзоры исправлений ошибок и откатов к прежним версиям Рано или поздно вам придется исправлять ошибки. При этом вы должны не под- даваться соблазну заняться другими задачами, чтобы не усложнить обзор кода и не затруднить регрессионное тестирование или откат ваших изменений другими поль- зователями. Исправление ошибки должно быть сосредоточено исключительно на исправлении конкретной ошибки и (обычно) обновлении соответствующих тестов, чтобы с их помощью можно было заметить ошибку. Устранение ошибки с помощью исправленного теста часто является срочной необхо- димостью. Ошибка появилась, потому что существующие тесты были недостаточно точны или код основывался на определенных предположениях, которые не были выполнены. Рецензент, исследующий предложенное исправление ошибки, должен запросить обновленные юнит-тесты при необходимости. Иногда изменение в кодовой базе с размером, как в Google, приводит к нарушению зависимости, которая либо не обнаруживается тестами, либо обнаруживается в не- проверенной части кодовой базы. В Google разрешается «откатывать» такие измене- ния, как правило, пострадавшим нижестоящим клиентам. Откат — это по существу изменение, отменяющее предыдущее изменение. Такие откаты могут создаваться за считаные секунды, потому что они возвращают код в известное состояние, но они тоже требуют обзора кода. Также очень важно, чтобы любое изменение, способное спровоцировать потенци- альный откат (включающий все изменения!), имело минимально возможный раз- мер и было атомарным, чтобы откат не вызвал нарушений в других зависимостях. Мы в Google видели, насколько быстро разработчики начинают зависеть от нового кода после его принятия, в результате чего откат изменений иногда мешает работе инженера. Чем меньше такие изменения, тем быстрее решаются связанные с ними проблемы благодаря их атомарности. Обзоры результатов рефакторинга и крупномасштабных изменений В Google многие изменения генерируются автоматически: автором таких изменений является не человек, а машина. (Подробнее о процессе крупномасштабных изме- нений (LSC, large-scale change) в главе 22.) Даже сгенерированные машиной изме- нения требуют обзора. Когда изменение сопряжено с небольшими последствиями, оно проверяется назначенными рецензентами, имеющими право давать одобрение для всей кодовой базы. Но когда изменение считается рискованным или требует особых знаний в предметной области, отдельным инженерам может быть предло- жено просмотреть автоматически сгенерированные изменения в ходе их обычного рабочего процесса. На первый взгляд обзор автоматически сгенерированного изменения должен про- водиться так же, как любого другого, — рецензент должен проверить правильность и уместность изменения. Однако мы рекомендуем рецензентам ограничить добав- ление комментариев и отмечать только те проблемы, которые относятся к их коду, Итоги 185 а не к базовому инструменту или процессу, сгенерировавшему изменения. Несмотря на то что конкретное изменение может быть сгенерировано машиной, сам процесс, сгенерировавший его, уже был рассмотрен, и отдельные группы не могут наложить вето на этот процесс, иначе будет невозможно масштабировать такие изменения по всей организации. Если существующее применение процесса или инструмента вы- зывает обеспокоенность, рецензенты могут обратиться за дополнительной инфор- мацией к группе надзора за крупномасштабными изменениями. Мы также предлагаем рецензентам автоматических изменений не выходить за рам- ки своей компетенции. При обзоре новой функции (или изменения), написанной товарищем по команде, часто разумно попросить автора рассмотреть связанные с изменением проблемы и учесть советы, чтобы сохранить изменение небольшим. Но рецензент, запускающий инструмент, может получить сотни изменений, и ком- ментирование даже небольшой их доли только ограничит область применения инструмента. Заключение Обзор кода — один из самых важных процессов в Google. Он действует как плат- форма для взаимодействия инженеров и является основным рабочим процессом разработчика. От обзора кода зависят почти все другие процессы, от тестирования до статического анализа и непрерывной интеграции. Процесс обзора кода должен масштабироваться и соответствовать передовым практикам (ограничению размеров изменений и ускорению обратной связи), которые помогают поддерживать удовлет- воренность разработчика и высокую скорость разработки. Итоги y Обзор кода имеет множество преимуществ, включая обеспечение правильности, понятности и согласованности изменения с базой кода. y Всегда сверяйте свои предположения с мнением коллег, чтобы оптимизировать код для читателей. y Реагируйте на критические отзывы как профессионал. y Обзоры кода способствуют обмену знаниями внутри организации. y Автоматизация — важное условие для масштабирования процесса обзора кода. y Обзор кода является хронологической записью. ГЛАВА 10 Документация Автор: Том Маншрек Редактор: Риона Макнамара Особенно сильным разочарованием большинства инженеров, пишущих, использу- ющих и сопровождающих код, является отсутствие качественной документации. «Какие побочные эффекты имеет этот метод?», «Я столкнулся с ошибкой, выполнив шаг 3!», «Что означает эта аббревиатура?», «Этот документ актуален?» Каждый инженер-программист хотя бы раз высказывал претензии к низкому качеству, не- достаточному объему или полному отсутствию документации, и программисты в Google не исключение. Несмотря на участие технических писателей и руководителей проектов, большую часть документации приходится писать самим инженерам-программистам. Поэтому инженерам нужны соответствующие инструменты и стимулы, чтобы эффективно справляться с этой работой. Облегчить создание качественной документации им поможет внедрение процессов и инструментов, которые масштабируются вместе с организацией и связаны с текущими рабочими процессами. По уровню развития создание технической документации в конце 2010-х годов напо- минало тестирование ПО в конце 1980-х. Все понимают, что необходимо приложить больше усилий для совершенствования процессов документирования, но пока нет повсеместного признания их важности. Ситуация меняется, хотя и медленно. Мы в Google добились определенного успеха в этом направлении, когда документацию стали рассматривать как код и включили ее написание и поддержку в повседневный рабочий процесс инженера. Что считается документацией? Под словом «документация» мы подразумеваем любой дополнительный текст, ко- торый инженер должен написать в процессе своей работы: не только отдельные до- кументы, но также комментарии в коде. (Фактически большая часть документации, которую пишет инженер в Google, имеет вид комментариев в коде.) Далее в этой главе мы обсудим различные виды технических документов. Зачем нужна документация? 187 Зачем нужна документация? Качественная документация дает огромные преимущества инженерной организации. Благодаря ей код и API становятся более понятными, что способствует уменьшению количества ошибок. Команды действуют более эффективно, когда их цели четко определены в документации. Ручные процессы легче выполнять, когда все шаги четко прописаны. Вливание новых членов в команду или знакомство с новой базой кода требует гораздо меньше усилий, если рабочий процесс ясно задокументирован. Но поскольку все преимущества наличия документации достаются тем, кто придет потом, они, как правило, не приносят выгоды ее автору, в отличие от тестирования (как мы увидим). Но, как бы то ни было, документ, написанный однажды 1 , будет прочитан сотни или даже тысячи раз, и первоначальные усилия на его создание бу- дут компенсированы уменьшением усилий всех будущих читателей. Документация масштабируется и приносит пользу не только ее будущим читателям, но и нынешним коллегам ее автора, что не менее важно. Она помогает ответить на такие вопросы: y Почему были приняты такие проектные решения? y Почему код реализован именно так? y Почему я выбрал именно такую реализацию? (Пару лет спустя спросите вы, глядя на свой код.) Если документация несет все эти преимущества, почему инженеры не любят писать ее? Одна из причин, как уже упоминалось, заключается в отсутствии немедленных выгод для автора. Но есть и другие причины: y Инженеры часто рассматривают документирование как отдельный навык, не связанный с программированием. (Мы попробуем показать, что это не совсем так, даже в тех случаях, где это мнение вполне обоснованно.) y Некоторые инженеры не считают себя хорошими писателями. Но вам не нужна надежная команда по английскому языку 2 , чтобы писать хорошую документацию. Вам просто нужно выйти за привычные рамки и посмотреть на вещи со стороны. y Писать документацию часто труднее из-за ограниченной инструментальной под- держки или слабой интеграции в рабочий процесс. y Документация рассматривается как дополнительная нагрузка — что-то еще, что требует поддержки, а не средство, облегчающее сопровождение существующего кода. Далеко не каждой команде инженеров нужен технический писатель (который все равно не справится со всей документацией). Это означает, что в общем случае инженеры будут писать большую часть документации самостоятельно. Поэтому вместо того чтобы заставлять инженеров становиться техническими писателями, мы должны по- 1 Конечно, вам придется его поддерживать и периодически пересматривать. 2 Английский по-прежнему считается основным языком для большинства программистов, и большая часть технической документации для программистов опирается на понимание английского языка. 188 Глава 10. Документация думать о том, как упростить написание документации. Рано или поздно организации придется принять решение о том, сколько усилий нужно посвятить документированию. Документация выгодна разным группам. Авторам документация дает следующие преимущества: y Помогает сформулировать API и оценить его пригодность. Часто документирова- ние приводит к переоценке проектных решений, которые не вызывали сомнений. Если вы не можете объяснить и определить что-то, то вы, вероятно, недостаточно хорошо это проработали. y Служит хронологической записью для сопровождающих. Хитросплетений в коде следует избегать в любом случае, но если они есть, хорошие комментарии помогут понять их в коде, написанном пару лет назад. y Делает код более профессиональным и привлекательным. Среди разработчиков бытует мнение, что хорошо документированный API — это хорошо проработанный API. Это не всегда так, хотя часто эти два аспекта тесно связаны друг с другом: наличие хорошей документации обычно является верным показателем того, на- сколько просто будет сопровождать продукт. y Уменьшает поток вопросов от пользователей. Это, пожалуй, самое большое пре- имущество для тех, кто пишет документацию. Если вам приходится снова и снова что-то объяснять, обычно имеет смысл задокументировать этот момент. Как бы ни были велики эти преимущества для автора документации, львиная доля выгод от нее, естественно, достается читателю. Руководство по стилю для C++ в Google особо подчеркивает принцип «оптимизации для читателя» ( https://oreil.ly/ zCsPc ). Этот принцип применим не только к коду, но также к комментариям в коде и документации, прилагаемой к API. Со временем ценность документации только рас- тет и может принести огромные выгоды для важного кода в масштабах организации. |