Предпочитаю примеры документации. Это поведенческая проблема?

Всякий раз, когда я сталкивался с новым API или языком программирования или даже простыми справочными страницами Linux , я всегда (с тех пор, как я себя помню) избегал их и вместо этого лениво полагался на примеры для получения понимания новых концепций.

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

Как мне избавиться от этой дурной привычки как программиста или я слишком много думаю?

Привычка полагаться на предпочтения в примерах не имеет ничего плохого: для вас это просто самый быстрый способ получить ответ. Более того, примеры наглядны. Проще визуально разобрать пример, чем читать текстовые абзацы и извлекать необходимую информацию.

Пример:

Чтобы составить список продуктов, следует использовать Indexдействие Productsконтроллера, учитывая, что GETэто единственный возможный глагол здесь (см. [Влияние на продукты] для получения дополнительной информации о действиях, используемых для создания, изменения и удаления продуктов из базы данных).

Чтобы получить подробную информацию о конкретном продукте, добавьте его уникальный идентификатор в конец URI. Если вы хотите получить список всех доступных продуктов, не добавляйте ничего. Вы также можете использовать фильтры, как описано в разделе [Фильтры REST для выбора данных] руководства. Обратите внимание, что список товаров ограничен тысячей наименований. [Пагинация] может использоваться для просмотра всего списка, учитывая, что каждая страница по-прежнему ограничена тысячей элементов.

Вы также можете заставить службу обновлять количество на складе. Это делается путем установки на refresh-quantitiesодин.

подробный, но скучный и едва читаемый. Тот факт, что вам нужно переходить по ссылкам, делает ситуацию еще хуже. Если мы добавим несколько примеров, это станет намного проще для понимания:

GET Products / Index /
GET Products / Index / 12345 /
GET Products / Index /? Skip = 100 & take = 20
GET Products / Index /?
Category = 12 GET Products / Index /? Price = 0..39.90
GET Products / Index /? категория = 12 & пропустить = 100 & принять = 20

Тот факт, что вы используете только примеры, может быть проблемой. Не прекращайте использовать примеры, но помните, что как только у вас появится идея, может помочь более подробная документация. Например, приведенный выше пример не показывает, что список продуктов ограничен 1 000: вы должны прочитать документацию для этого.

Когда вы знаете, что вам следует прочитать документацию?

Каждый раз, когда API или библиотека ведут себя не так, как вы ожидали. Например, вы берете образец и делаете:

ПОЛУЧИТЬ Продукты / Индекс /? Skip = 6000 & take = 3000

По какой-то причине он возвращает менее 3000 наименований, а у вас в базе данных более двадцати тысяч товаров. Здесь API работает не так, как вы ожидали, поэтому самое время прочитать подробную документацию.

Информация, предоставленная документацией, делится на три категории:

• Рецепт.
• Ссылка.
• Экспертные знания.

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

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

Как мне избавиться от этой дурной привычки как программиста или я слишком много думаю? Любая мудрость от коллег-программистов приветствуется.

Я не думаю, что ваша привычка плохая. Когда вы изучаете API, вы сначала получаете представление о том, какие проблемы могут быть решены и какие методологии предоставляются с помощью рецептов (ваши примеры). Затем справочная документация поможет вам точно настроить методологии для особых случаев.

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

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