Делай как вGoogle
 Скачать 5.77 Mb.
|
|
202 Глава 10. Документация кодом, который документ описывает. Но можно использовать и другие храни- лища. Мы в Google часто используем Google Docs, чтобы упростить совместную работу, особенно с проектными документами. Однако в какой-то момент обсуж- дение любого общего документа заканчивается, и он становится хронологической записью. В этот момент желательно переместить документ в более надежное место, обеспечивающее права владения, управление версиями и ответственность. y ПОЧЕМУ объявляет цель документа. Кратко опишите, что читатели смогут по- черпнуть из документа. Хорошая практика — перечислить разные ПОЧЕМУ во введении к документу. Когда вы будете писать заключение, проверьте, сбылись ли ваши первоначальные ожидания (и внесите соответствующие правки). Начало, середина и конец Все документы — и все их части — имеют начало, середину и конец. Эти слова могут показаться странными, но большинство документов должны содержать как мини- мум эти три раздела. Документ, включающий только один раздел, может охватить только одну тему, при этом очень немногие документы действительно описывают единственную тему. Не бойтесь добавлять разделы в документы — они разбивают поток повествования на логические части и помогают читателям быстро оценить, какие темы в документе представлены. Даже в самом простом документе обычно рассматривается больше одной темы. Наши популярные «Советы недели для C++» очень короткие и основное внимание уде- ляют одному небольшому совету. Однако даже в них деление на разделы приносит дополнительные выгоды. Традиционно первый раздел описывает проблему, второй рассматривает рекомендуемые решения, а в последнем подводятся итоги. Если бы документ состоял только из одного раздела, читателям было бы трудно вычленить в нем важные моменты. Большинство инженеров ненавидят избыточность, и тому есть причины. Но в доку- ментации избыточность бывает полезна. Порой трудно заметить и запомнить важный момент, спрятанный за стеной текста. С другой стороны, более раннее описание такого момента в более заметном месте может привести к потере его контекста. Ти- пичное решение этой проблемы состоит в том, чтобы кратко представить тот момент во вступительном абзаце, а в остальной части раздела изложить свою точку зрения более подробно. В этом случае избыточность поможет читателю понять важность того, о чем говорится. Признаки хорошей документации Типичными признаками хорошей документации являются полнота, точность и яс- ность. Редко удается совместить все три признака в одном документе: например, более «полный» документ, скорее всего, будет менее ясным. Документируя все ва- рианты использования API, вы получите очень запутанный документ. В документах с описанием языка программирования полная точность в отношении всех вариантов Философия документирования 203 использования (и перечисление всех побочных эффектов) тоже может нанести ущерб ясности. В других документах попытка прояснить сложную тему может повлиять на точность. В концептуальном документе можно опустить редкие побочные эффекты, потому что его цель — познакомить читателя с API, а не представить скрупулезный обзор всех вариантов поведения кода. В любом случае, «хорошим» можно считать документ, который соответствует своему назначению. Поэтому нежелательно создавать документы с несколькими назначениями. Определите направленность каждого документа (и каждый тип документов) и пишите их соответствующим образом. Пишете концептуальный до- кумент? Тогда вам не нужно расписывать API во всех деталях. Пишете справочник? Тогда уделите внимание точности, пусть и за счет некоторой потери ясности. Пишете домашнюю страницу? Сосредоточьтесь на ее организации и постарайтесь сократить описательный текст до минимума. Все это — слагаемые качества, которое, по общему признанию, трудно измерить. Как быстро улучшить качество документа? Сосредоточиться на потребностях ауди тории. Часто чем меньше, тем лучше. Например, многие инженеры допускают распространенную ошибку, добавляя описание проектных решений или деталей реализации в документ по API. Так же как вы отделяете интерфейс API от его реализации, избегайте обсуждения проектных решений в документе по API. Поль- зователям не нужна эта информация. Лучше опишите эти решения в отдельном документе (обычно проектном). Устаревшие документы Проблемы может вызывать не только устаревший код, но и устаревшие документы. Со временем документы устаревают и (нередко) забываются. Старайтесь не за- бывать документы, и если документ перестал служить своей цели, удалите его или обозначьте как устаревший (и если возможно, укажите, куда обратиться за актуаль- ной информацией). Даже добавить простое примечание «Это больше не работает!» намного полезнее, чем оставить в неизменном виде документ, который выглядит авторитетным, но больше не актуален. Мы в Google часто включаем упоминание о «свежести документа». Такие упоминания фиксируют дату, когда в последний раз документ пересматривался, и, основываясь на ней, система сопровождения документации отправляет владельцу напоминания по электронной почте, если документ не пересматривался, например, более трех месяцев. Такие даты обновления, как показано в следующем примере, свидетель- ствующие об ошибочности документов, могут помочь упростить сопровождение набора документации с течением времени: # Дата обновления: за дополнительной информацией обращайтесь по ссылке # go/fresh-source. freshness: { owner: `username` reviewed: '2019-02-27' } *--> 204 Глава 10. Документация Владельцы таких документов получают стимул поддерживать актуальность даты об- новления (а если документ находится под контролем VCS, еще и стимул пересмотреть код). Это недорогое средство способствует периодической проверке документации. Мы в Google обнаружили, что добавление в документ упоминания о его владельце с подписью «Последний пересмотр...» также способствовало распространению прак- тики пересмотра документации. Когда привлекать технических писателей? Когда Google была молодой и растущей компанией, в сфере программной инженерии ощущалась нехватка технических писателей. (Впрочем, их не хватает и сейчас.) Те проекты, которые считались важными, стремились привлечь к работе техническо- го писателя независимо от того, была ли в этом необходимость. Идея заключалась в том, что писатель должен был снять с команды часть бремени написания и ведения документов и (теоретически) позволить важному проекту достичь более высокой скорости разработки. Эта идея себя не оправдала. Как показал наш опыт, большинство команд инженеров отлично справляются с написанием документации для себя (своих команд), но когда речь заходит о до- кументации для другой аудитории, инженеры ищут помощи технического писателя. Петля обратной связи внутри команды при написании документов более короткая, а знание предметной области и предполагаемые потребности более очевидны. Конеч- но, технический писатель часто лучше справляется с грамматикой и организацией документов, но поддержка единственной команды — не лучшее использование такого ограниченного и ценного ресурса, как технический писатель, поскольку такой подход не масштабируется. В итоге появился неверный стимул: станьте важным проектом, и вашим инженерам-программистам не придется писать документы. Отгораживание инженеров от написания документов, как оказалось, — это совсем не то, что вам нужно. Будучи ограниченным ресурсом, технические писатели, как правило, сосредоточены на задачах, которые не должны выполняться инженерами-программистами в рамках своих обязанностей. Обычно к таким задачам относится написание документов, выходящих за рамки API. Команда проекта Foo может четко понимать, какая до- кументация нужна, но с трудом представлять, что нужно проекту Bar. Технический писатель лучше справится с ролью человека, не знакомого с предметной областью. Фактически очень полезно оспаривать предположения команды относительно по- лезности проекта. Это одна из причин, по которой многие, если не большинство тех- нических писателей, в сфере программной инженерии склонны концентрироваться на конкретном типе документации по API. Заключение За последние десять лет мы в Google добились значительных успехов в решении проблемы качества документации, но, честно говоря, документация в Google все Итоги 205 еще не является образцом для подражания. Для сравнения, инженеры постепенно осознали, что тестировать необходимо любое изменение в коде, каким бы малым оно ни было. Более того, в разные этапы технологического процесса были включены разнообразные и надежные инструменты тестирования. Однако документации еще далеко до этого уровня. Впрочем, справедливости ради следует признать, что с документацией не обязательно обращаться так же, как с тестированием. Тесты могут быть атомарными (юнит-тесты) и соответствовать предписанной форме и функциям. Для документов это по большей части невозможно. Тестирование можно автоматизировать, а методики автомати- зации ведения документации часто отсутствуют. Документы всегда субъективны; качество документа оценивается читателем, и зачастую спустя время. Тем не менее уже есть понимание важности документации, и процессы, связанные с разработкой документов, постепенно совершенствуются. По мнению автора этой главы, качество документации в Google намного выше, чем в большинстве софтверных компаний. Чтобы изменить качество технической документации, инженеры и организация в целом должны осознать, что они одновременно являются и проблемой, и решением. Вместо того чтобы закрывать глаза на состояние документации, они должны понять, что создание качественной документации является частью их работы и экономит их время и силы в долгосрочной перспективе. Документирование любого фрагмента кода, который просуществует больше нескольких месяцев, поможет его поддерживать не только другим, но и вам самим. Итоги y Документация приносит пользу организации не только в будущем, но и сейчас. y Работа над документацией должна быть включена в рабочий процесс разработ- чика. y Каждый документ должен иметь одно назначение. y Пишите для других, а не для себя. ГЛАВА 11 Основы тестирования Автор: Адам Бендер Редактор: Том Маншрек Тестирование всегда было неотъемлемой частью программирования. Написав свою первую программу, вы наверняка опробовали ее с несколькими примерами данных, чтобы убедиться, что она работает так, как ожидалось. Долгое время тести- рование ПО напоминало этот процесс, проводилось вручную и было подвержено ошибкам. Однако с начала 2000-х годов подход к тестированию в индустрии ПО претерпел значительные изменения, как того требовал рост размеров и сложности программных систем. Центральное место в этих изменениях заняла автоматизация тестирования. Автоматическое тестирование способно предотвратить проникновение ошибок в ди- кую природу кода и их влияние на пользователей. Чем позже в цикле разработки обнаруживается ошибка, тем дороже обходятся ее последствия, причем во многих случаях эта дороговизна растет экспоненциально 1 . Однако «ловля жуков» является лишь одним из мотивов для тестирования ПО. Независимо от того, добавляете вы новые функции, выполняете рефакторинг для поддержки кода в здоровом состо- янии или проводите переоценку ПО, автоматизированное тестирование поможет быстро выявить ошибки и тем самым позволит с большей уверенностью вносить изменения в ПО. Компании вынуждены быстро адаптироваться к изменениям в технологиях, усло- виях рынка и вкусах клиентов. Использование надежной практики тестирования избавит вас от страхов перед изменениями и станет для вас неотъемлемой частью процесса разработки ПО. Чем чаще и быстрее вам потребуется менять свои системы, тем выше будет ваша потребность иметь быстрый способ тестирования изменений. Сам акт написания тестов способствует улучшению дизайна систем. Как первый кли- ент кода тест может многое рассказать о его дизайне. Не слишком ли тесно система связана с базой данных? Поддерживает ли API требуемые варианты использования? Обрабатывает ли система все крайние случаи? Написание автоматических тестов помогает ответить на эти вопросы на ранних этапах разработки и делает ПО более модульным и гибким. 1 См. статью «Defect Prevention: Reducing Costs and Enhancing Quality» ( https://oreil.ly/27R87 ). Почему мы пишем тесты? 207 Много чернил было израсходовано на описание тестирования ПО, и это вполне объяснимо: несмотря на всю свою важность, практика тестирования до сих пор многим кажется загадочной. Мы в Google прошли долгий путь, но все еще сталкива- емся с трудностями, препятствующими распространению наших процессов по всей компании. В этой главе мы поделимся с вами своими знаниями, чтобы вы смогли развить наши идеи. Почему мы пишем тесты? Чтобы лучше понять, как получить максимальную отдачу от тестирования, начнем с самого начала. Что мы в действительности подразумеваем, говоря об автоматизи- рованном тестировании? Самый простой тест определяется: y единственным тестируемым поведением, обычно методом или API; y конкретными входными данными — значением, которое передается в API; y наблюдаемым результатом или поведением; y управляемой средой, такой как отдельный изолированный процесс. Выполняя тест, передав входные данные в систему и проверив результат, можно узнать, действует ли система так, как ожидается. Совокупность из сотен или тысяч простых тестов (обычно называемая набором тестов) может поможет выявить не- соответствия кода предполагаемому дизайну. Создание и поддержка надежного набора тестов требуют больших усилий. Вместе с ростом кодовой базы растет и набор тестов, что вызывает проблемы в их стабиль- ности и скорости. Игнорирование этих проблем отрицательно сказывается на наборе тестов. Имейте в виду, что главная ценность тестов заключается в доверии к ним со стороны инженеров. Если продуктивность инженеров снижается из-за постоянной поломки тестов и появления неопределенности, инженеры потеряют доверие к те- стам и начнут пытаться их обойти. Плохой набор тестов воспринимается хуже, чем полное их отсутствие. Помимо возможности быстро создавать качественные продукты тестирование обе- спечивает безопасность продуктов и услуг. Постепенно ПО все глубже проникает в нашу жизнь, и дефекты в нем могут вызывать не только раздражение: они могут при- водить к огромным убыткам, потере имущества или, что хуже всего, к гибели людей 1 Мы в Google убедились, что тестирование — это далеко не второстепенный вопрос. Внимательное отношение к качеству ПО и тестированию является частью нашей работы. На своем опыте, иногда горьком, мы узнали, что неспособность обеспечить высокое качество продуктов и услуг неизбежно приводит к плохим результатам. Поэтому мы включили тестирование в основу нашей инженерной культуры. 1 См. статью «Failure at Dhahran» ( https://oreil.ly/lhO7Z ). 208 Глава 11. Основы тестирования История Google Web Server В первые дни существования Google многие инженеры считали тестирование чем-то малозначительным. Команды полагались на умение людей писать ПО без ошибок. Некоторые системы подвергались масштабному интеграционному тестированию, но в основном они напоминали Дикий Запад. Больше всего пострадал один из наших продуктов Google Web Server, также известный как GWS. GWS — это веб-сервер, отвечающий за обслуживание запросов к Google Search и управление воздушным движением в аэропортах. Еще в 2005 году, когда размер и сложность проекта увеличились, скорость его разработки резко упала. Реализации становились все более громоздкими, а периоды между ними становились все боль- ше. Члены команды испытывали неуверенность при внесении изменений в службу и часто обнаруживали, что что-то не так, только когда какие-то функции переставали работать в продакшене. (В какой-то момент более 80 % изменений в продакшене со- держали ошибки, влияющие на пользователя, и их требовалось откатить.) Для решения этих проблем технический лидер проекта GWS решил использовать автоматизированное тестирование. Согласно этому решению все новые изменения должны были включать тесты, выполняемые непрерывно. Спустя год число чрез- вычайных происшествий в проекте сократилось наполовину, несмотря на то что в каждом квартале вносилось рекордное число изменений. Даже в условиях бес- прецедентного роста числа изменений тестирование способствовало увеличению скорости разработки одного из самых важных проектов в Google. В настоящее время в GWS выполняются десятки тысяч тестов и его новые реализации выходят почти каждый день, но при этом число сбоев, видимых клиенту, остается незначительным. Изменения в политике разработки GWS ознаменовали перелом в культуре тести- рования в Google, так как команды в других подразделениях компании увидели преимущества тестирования и перешли на аналогичную тактику. Самый важный урок, который мы вынесли из опыта разработки GWS: нельзя избе- жать дефектов в программном продукте, полагаясь только на способности програм- мистов. Даже если каждый инженер допустит по случайности только одну ошибку, команду таких инженеров захлестнет постоянно растущий список дефектов. Пред- ставьте гипотетическую команду из 100 хороших инженеров, каждый из которых допускает только одну ошибку в месяц. В совокупности эта группа выдающихся программистов будет добавлять пять новых ошибок каждый рабочий день. Что еще хуже, исправляя одну ошибку в сложной системе, инженеры могут по неосторож- ности внести другую ошибку. Лучшие команды ищут способы использовать коллективную мудрость. Автомати- зированное тестирование — один из таких способов. Когда инженер в команде на- пишет тест, он добавляет его в пул общих ресурсов, после чего другие члены команды могут применить этот тест и получить выгоду от обнаружения проблемы. Сравните этот подход с подходом, основанным на отладке, при котором, обнаружив ошибку, инженер должен потратить время, чтобы найти причину этой ошибки с помощью |