Ви повинні бути обережними, щоб не додавати новий словник лише заради вашого API. Мої улюблені API пояснюють мені речі, які я вже розумію. По цих лініях:
Не додайте занадто багато абстракцій поверх того, що ви будуєте. Не ускладнювати.
Мені вже доводиться думати про півтора десятка шарів абстракції. Не змушуйте мене думати про зайві шари. Не дайте мені занадто багато нового, щоб дізнатися, що не додасть значення моїй кінцевій цілі. Наприклад, уникайте використання власного спеціального класу файлів, який працює по-іншому, тоді як тип файлу мови просто змушує вас вважати ваш шлях кращим, ніж загальноприйнятий спосіб. Дотримуйтесь загальноприйнятого способу, принаймні у своїх інтерфейсах, на краще або на гірше.
Дотримуйтесь конкретних ідей
Наприклад, не намагайтеся приховати той факт, що "модельна" частина вашого MVC-фрейму є передньою частиною бази даних. Скористайтеся загальновідомою лексикою навколо "баз даних". Я знаю, що таке іноземні ключі. Я знаю, що таке рядки та стовпці. Поговоріть зі мною в цих умовах.
Не абстрагуйте необхідних знань
Подібно до роботи з конкретними ідеями. Не приховуйте того, що ми маємо справу з файлами чи базами даних або рядками в базах даних. Я знаю ці речі. Якщо я маю справу з контейнером, як List, є хороший шанс, що мені потрібно знати алгоритмічну складність загальних операцій. Ви можете спростити це багато, просто сказавши мені його "пов'язаний список" або "масив". Величезний набір ідей раптом з’явиться у відповідь на те, що ви робите, і це раптом має сенс. Не створюйте власний набір ідей, які мені доведеться вивчити, коли я вже знайду багатий і корисний набір термінології, щоб застосувати проблему.
Скоротіть кількість потрібних мені термінів у своєму словниковому запасі
Якщо я використовую ваш API для відкриття файлів зображень будь-якого типу, мені не доведеться дуже думати про pngs vs gifs vs jpgs. Ти зробиш це для мене. Його основна компетенція, а не моя. Я маю деяке розпливчасте розуміння того, що ти маєш якусь магію зробити це для мене.