Вы начинаете работать над задачей, вы находите библиотеку, в которой есть все необходимое. Вы начинаете пользоваться библиотекой, а потом получаете ошибку. Вы смотрите документацию библиотеки, но ничего не слышите о проблеме, с которой столкнулись. Кто-то задал тот же вопрос в StackOverflow, но решение пока не опубликовано. Если это звучит знакомо, это потому, что это случилось с вами в какой-то момент (при условии, что вы программист). На этом этапе вы можете бросить, бросить работу, переехать в сельскую местность или использовать некоторые из стратегий, которые мы рассмотрим в этой статье.

Понимание документации

Прежде чем отказываться от документации, давайте рассмотрим способы ее изучения. Как и в технических книгах, мне нравится быстро пролистывать весь материал. Моя цель не в том, чтобы изучить его, а в том, чтобы получить представление об охвате документации. Как только я знаю, что он охватывает и до какой глубины, я могу решить, в какие части мне стоит инвестировать. Возьмем недавний пример.

Одна из стоящих передо мной задач заключалась в разработке системы очередей с приоритетами для нашей внутренней системы, которая заменила бы SQS как форму связи между службами. Моя первая цель состояла в том, чтобы найти возможные решения, которые позволят нам создать очередь с приоритетом, способную обрабатывать задачи с произвольным приоритетом. Возможными инструментами, которые помогли мне добиться этого, были RabbitMQ, ZeroMQ и Redis. Моей первой целью при просмотре их соответствующей документации было найти любую функцию, которая может быть использована для решения моей проблемы. В документации не обязательно будет использоваться термин, который может возникнуть у вас в голове, поэтому нам нужно получить общее представление о доступных нам API. Быстро просмотрев документацию по API, я пришел к выводу, что Redis имеет все необходимые API для достижения желаемого результата. На тот момент я еще не знал точно, как использовать API, но знал, какие из них существуют. (Примечание: API, который я использовал, полагается на модель данных под названием sorted set, и мы можем адаптировать ее к нашему варианту использования.)

Как только я остановился на технологии, я глубоко погрузился в документацию Redis. К счастью, он подробно описан с хорошими примерами. Я все это прочитал? Нет, я пропустил части, не относящиеся к моей задаче, такие как аспекты Redis, связанные с развертыванием.

Один шаг, который я пропустил в своем описании шагов, предпринятых до сих пор; Прежде чем погрузиться в документацию, я использовал поисковую систему, чтобы сузить список технологий, которые могут подойти для моей задачи.

Для разработчиков более интересным местом для поиска является GitHub, он предлагает расширенный поиск, который можно использовать для поиска примеров использования функций, внутреннего устройства модуля, который мы используем, или некоторых комментариев, оставленных разработчиками. Я часто использую эту функцию, чтобы определить, как другие создали свои проекты и структурировали их. Давайте посмотрим на некоторые случаи.

Наблюдать за другими

Когда мы настраивали наше интерфейсное приложение, я хотел знать, как правильно настроить проект. Одним из преимуществ и недостатков мира разработки JS является то, что существуют сотни способов достижения той же функциональности. Однажды мы решили использовать Next.js, фреймворк для разработки приложений React. Нам нужно было настроить его для работы с разными наборами подключаемых модулей для нашего интерфейсного приложения. Чтобы посмотреть, как это сделали другие, я зашел на GitHub и поискал следующее:

filename:next.config.js

Результат поиска показывает мне все репозитории с конфигурацией Next.js. Термин «имя файла» - это ключевое слово для расширенного поиска Github. Мы указываем имя файлов, в которых хотим выполнить поиск, добавляя его к ключевому слову, разделенному двоеточием. В этом случае я даже не ищу в файле, а просто ищу его наличие, поскольку для всех проектов Next.js требуется файл next.config.js.

Наше приложение также использует postcss, поэтому мы хотим увидеть пример конфигурации с postcss.

filename:next.config.js postcss

Как только мы обновим наш поисковый запрос, мы вернем все следующие проекты js с настраиваемой конфигурацией postcss. Аккуратно. Вы можете найти удобную страницу со всеми функциями расширенного поиска на github здесь.

Поиск в темноте

В предыдущем примере я искал примеры проектов, чтобы у них поучиться. Мы также можем использовать функцию поиска, чтобы узнать, как люди используют определенные функции модуля, который вы используете. Когда я работал над проектом Django, у меня был конкретный вариант использования MultiChoiceField на seriliaser. Я хотел предоставить значения выбора MultiChoiceField из результата запроса к базе данных. Чтобы узнать, возможно ли это сделать, я просмотрел официальную документацию, которая не дала четкого ответа. Затем я зашел на GitHub и поискал extension:py MultipleChoiceField.

Результаты показали мне разные способы использования поля людьми, и один из примеров, на который я наткнулся, был тем же образцом, который я собирался использовать. Я мог бы также узнать, возможно ли это, попробовав, но я был ленив и не настраивал проект локально.

Следующей задачей было придумать более сложный вариант использования в этой области. Мы хотим иметь настраиваемую ошибку как часть ошибки сериализатора, и в документации Django Rest Framework (DRF) есть небольшой раздел об этой функции, но мы хотели, чтобы ошибка отображала ввод и список вариантов, доступных пользователю. У меня была интуиция, что это возможно, поскольку ошибка по умолчанию показывает исходный ввод пользователя как часть сообщения об ошибке.

Это подводит меня к следующему этапу работы с нехваткой документации.

Все дороги ведут к исходному коду.

Долгое время я иррационально боялся читать первоисточник проектов. Возможно, это связано с моим предыдущим опытом погружения в код лазаньи мира Java / Scala. Иногда это может показаться сложным, и некоторые проекты не поддаются легкому чтению, но попробовать стоит. Я считаю, что исходный код проектов Python и TypeScript вполне читабелен. Читая исходный код DRF, мы выяснили, что сериализатор использует .format в строке с заполнителем исходного пользовательского ввода, заданным как {input} в строке. Изучив документацию, мы приходим к красивому и лаконичному способу улучшить наши сообщения об ошибках в нашем сериализаторе.

Если ни одна из вышеперечисленных стратегий не принесла результата, вы всегда можете спросить своих коллег, друзей или людей в Интернете.

Я часто говорю, что умение искать - одно из моих лучших навыков. Мое предположение по умолчанию для любой задачи всегда заключается в том, что кто-то другой уже ее выполнил. Чтобы доказать это, я использую несколько терминов для поиска в StackOverflow, GitHub или на форуме проекта. Только если не найду доказательств этого, я начинаю задумываться о переезде в деревню.

P.S. Учитывая, что сейчас мы все работаем удаленно, переезд в деревню мне не поможет.

Автор Дониер Ульмасов, инженер-программист Papercup