Проектування API: в рамку і на стіну

       Кожен програміст — проектувальник API. Хороші програми складаються з модулів, а протокол взаємодії модулів — це теж API. Хороші модулі використовуються повторно.
 
 API — це велика сила і велика відповідальність. У хорошого API будуть вдячні користувачі; підтримка поганого перетвориться на кошмар.
 
 Публічне API — не горобець, опублікуєш — не прибереш. Є тільки одна спроба зробити все правильно, тому постарайся.
 
 API повинно бути легко використовувати, але складно використовувати неправильно. Зробити щось просте за допомогою такого API має бути просто; складне — можливо; зробити щось неправильно повинно бути неможливо, або, принаймні, важко.
 
 API має описувати саме себе. Вивчення коду на такому API не викликає бажання читати коментарі. Взагалі, коментарі рідко потрібні.
 
 Перед розробкою API збери вимоги з часткою здорового скептицизму. Усвідом спільні завдання і виріши їх.
 
 Оформляй вимоги як шаблони використання API. Звіряйся з ними в процесі проектування.
 
 У перших начерках API має бути коротким, зазвичай одна сторінка з сигнатурами і однорядковими описами. Якщо все не те, буде простіше переробляти.
 
 Закодуйте шаблони використання до реалізації API, навіть до докладного визначення. Завдяки цьому ти не витратиш час на принципово нежиттєздатне API.
 
 Змінюй код шаблонів використання в міру розвитку API. Це виключить неприємні сюрпризи. Потім шаблони можна буде вжити в прикладах, документації та тестах.
 
 Код прикладів повинен бути зразковим. Користувачі будуть копіювати його в свої програми. Найменша помилка відгукнеться сторицею.
 
 Не можна догодити всім і у всьому, прагни догодити всім однаково. Більшість API занадто заточені під потреби своїх творців, що позбавляє гнучкості.
 
 Будь готовий до власних помилок в дизайні API. Наївно вважати, що ти продумав все до єдиного сценарії використання API, побічні ефекти взаємодії з оточенням і т. д.
 
 При розробці API один у полі не воїн. Покажи API якомога більшому числу колег і сприймай критику. Вони можуть помітити твої помилки.
 
 Назви мають значення. Прагни ясності і симетрії. Будь послідовний. Кожне API — це маленький мову, користувачі будуть вчитися читати і писати на ньому. Код на хорошому API схожий на природний текст.
 
 Не виходить придумати гарні назви — повернися до проектування. Не бійся перелопачувати API. Якщо назви лягають одне до одного, ти на вірному шляху.
 
 Сумніваєшся — видаляй. Мабуть, головне правило розробки API. Стосується всього: блоків функціональності, модулів, класів, функцій, методів, параметрів. Кожна окрема частина API повинна бути такою маленькою, як тільки можливо, але не менше. Щось додати завжди встигнеш, а прибрати нічого не можна. Насамперед зменшуй кількість смислів, а не класів або методів.
 
 Стеж, щоб деталі реалізації не проникли в API. Це збиває користувачів і ускладнює розвиток API. Не завжди легко зрозуміти, що є деталь реалізації: Стережися надмірної подробиці. Наприклад, не вказуй в API алгоритм хеш-функції.
 
 Скорочуй змінюваність. Незмінні об'єкти прості і безпечні.
 
 Документація має значення. Ніхто не використовуватиме хороше API без документації. Описуй кожну публічну сутність: кожен клас, кожну функцію, кожен аргумент, кожне поле.
 
 Тримай в розумі наслідки рішень в архітектурі API для продуктивності, але не став її вище якості API. На щастя, гарне API звичайно дружить з високою продуктивністю.
 
 Не лізь зі своїм уставом у чужий монастир. API має органічно вписуватися в мову і платформу, слідувати угодам. Погана думка — переносити API з однієї платформи на іншу без змін.
 
 Скорочуй доступність. Сумніваєшся — роби приватним. Це спрощує API і зменшує зв'язність.
 
 Застосовуй спадкування, тільки якщо не кривлячи душею можеш сказати, що кожен екземпляр підкласу — екземпляр надкласса. Публічний клас не може успадковувати, тільки щоб повторно використовувати реалізацію.
 
 продумувати і документуються можливість наслідування, або забороняй його. Опиши в документації, як і коли методи класу викликають один одного. Без цього безпечне спадкування неможливо.
 
 Чи не змушуй користувача робити що-небудь за бібліотеку. Вірна ознака — повторюваний код при роботі з API. Це стомлює і загрожує помилками.
 
 Йди принципом найменшого подиву. Функція повинна робити щось найбільш очікуване від своєї назви і сигнатури.
 
 Прагни, щоб помилки при використанні спливали якомога раніше. Найкраще — під час компіляції. Під час виконання — бажано при першому ж помилковому виклику.
 
 Надай програмний доступ до всього, що доступно у вигляді тексту. Негуманно прирікати користувачів на розбір рядків. Гірше того, формат тексту фактично стане частиною API. Приклад: якщо можна надрукувати трасування стека, повинна бути можливість і отримати список посилань на фрейми.
 
 перевантажується методи / функції з обережністю. Якщо їх дію розрізняється, краще дати різні назви.
 
 Застосовуй самі відповідні типи. Наприклад, приймай і передавай IP-адресу як спеціальний тип, а не число або рядок.
 
 Тримайся одного порядку аргументів у функціях. Інакше користувачі все переплутають.
 
 Уникай довгих списків аргументів, особливо якщо кілька штук одного типу йдуть підряд.
 
 Методи не повинні повертати значення, що вимагають особливої ​​обробки. Користувачі будуть забувати про перевірки. Наприклад, повертай порожній масив або список, а не
null
.
 
 Винятки — тільки для виняткових ситуацій. Обробка винятків не повинна бути частиною основної логіки клієнтських програм. Це некрасиво, загрожує помилками і часто б'є по продуктивності.
 
 Кидай непроверяемие винятку, якщо користувач навряд чи зможе осмислено обробити помилку.
 
 Проектування API — мистецтво, а не наука. Думай про красу, довіряй інтуїції. Не будеш цим правилам сліпо, але порушуй їх лише зрідка і по значному приводу.
 
 

 Презентація і відео : те ж саме, але дещо іншими словами і з прикладами на Java.
  
Джерело: Хабрахабр

0 коментарів

Тільки зареєстровані та авторизовані користувачі можуть залишати коментарі.