Віддайте перевагу прикладам над документацією. Це проблема поведінки?

Кожного разу, коли я стикаюся з новою 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 /? Категорія = 12
GET Products / Index /? Ціна = 0..39.90
GET Products / Index /? категорія = 12 і пропустити = 100 і взяти = 20

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

Коли ви знаєте, що вам слід прочитати документацію?

Кожен раз, коли API чи бібліотека ведуть себе не так, як ви очікували. Наприклад, ви захоплюєте зразок і робіть:

GET Products / Index /? Пропустити = 6000 і взяти = 3000

Чомусь він повертає менше 3 000 предметів, тоді як у вашій базі даних є понад двадцять тисяч продуктів. Тут API не веде себе так, як ви очікували, тож прийшов час прочитати детальну документацію.

Інформація, надана документацією, поширюється на три категорії:

• Рецепт.
• Довідково.
• Експертні знання.

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

(Експертні знання пов'язують поняття проблемної області з поняттями документації; це корисно, якщо поняття можуть бути виражені кількома способами або якщо користувачі програмного забезпечення не є фахівцями в цій галузі.)

Як я порушую цю шкідливу звичку як програміст чи передумую? Будь-яка мудрість від колег-програмістів цінується.

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

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

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