Разработка лучшего API?

Q4:

• Как создать хороший API и почему это важно - Отличное видео, которое стоит потраченного времени на его просмотр.

На мой взгляд, у Джоша Блоха есть лучшие идеи, когда дело доходит до написания хороших API , и он может объяснить их очень легко для понимания. Видео выше будет адресовано вам Q1-3.

Самый безопасный способ (т. Е. Самый простой способ не допустить ошибки в вашем приложении) может заключаться в следующем.

Создайте интерфейс, который абстрагирует ваше использование TFS, например:

interface ITfs
{
  bool checkout(string filename);
}

Напишите класс, реализующий этот интерфейс с помощью TFS:

class Tfs : ITfs
{
  public bool checkout(string filename)
  {
    ... code here which uses the TFS assembly ...
  }
}

Напишите другой класс, реализующий этот интерфейс без использования TFS:

class NoTfs : ITfs
{
  public bool checkout(string filename)
  {
    //TFS not installed so checking out is impossible
    return false;
  }
}

Создайте где-нибудь синглтон:

static class TfsFactory
{
  public static ITfs instance;

  static TfsFactory()
  {
    ... code here to set the instance
    either to an instance of the Tfs class
    or to an instance of the NoTfs class ...
  }
}

Теперь есть только одно место, с которым нужно быть осторожным (например, TfsFactory конструктор); остальная часть вашего кода может вызывать методы ITfs вашего TfsFactory.instance, не зная, установлена ​​ли TFS.

Чтобы ответить на недавние комментарии ниже:

Согласно моим тестам (я не знаю, является ли это «определенным поведением» ') возникает исключение, когда (как только) вы вызываете метод, который зависит от отсутствующей сборки. Поэтому это ' актив для организации, написавшей это и всем, кто им пользуется. Учитывая важность хорошего дизайна API, на удивление мало написано по теме. В этом выступлении (записано в Javapolis), дизайнер библиотеки Java Джошуа Блох учит проектировать хорошие API, с множеством примеров того, что хорошие и плохие API выглядят так.

http://www.infoq.com/presentations/effective-api-design

Также вы можете прочитать книгу Практическое проектирование API: признание архитектора Java ™ Framework . Я не читал его, поэтому не уверен, может ли оно быть вам полезно.

Еще один ресурс для проверки: Как разработать (модуль) API

Apress - Практический дизайн API - Признание архитектора Java - 2008

Pragmatic - Интерфейсно-ориентированный дизайн - 2006

Ознакомьтесь с этим подкастом

В нем рассказывается о некоторых действительно хороших концепциях, касающихся дизайна api.

Прочтите Эффективная Java Джоша Блоха. Книга отлично подходит для любого Java-программиста, но также затрагивает множество вопросов, связанных с созданием полезного API.

На этот вопрос практически невозможно ответить. Это может быть даже неподходящий вопрос для переполнения стека (Человек A: Как мне решить конкретную проблему? Человек B: Вот этот окончательный ответ).

1. Каковы лучшие практики и шаблоны, которым следует следовать при проектировании API

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

2. Как добиться наилучшего сокрытия реализации (C ++ / Java)

На этот вопрос есть ответ , и писать здесь слишком долго. На самом деле, он настолько длинный, что ссылки на веб-сайт будет недостаточно. На этот вопрос ответят многие веб-сайты и книги. О, и я ' я просто говорю о C ++. Повторите весь этот процесс для Java. И для C #, и для Python, и для .... (и т. Д.)

4. Любые справочники / ссылки, которые содержат полезные примеры для начинающих

Выберите язык программирования. Затем я могу предоставить ссылки на книги и ссылки. Как писал Фред Брукс, серебряной пули не существует. Не существует единого менталитета, который можно было бы перенести с языка программирования на язык программирования. То, что делает хороший API на одном языке программирования, было бы ошибкой проектирования на другом языке программирования. Поверьте мне, я понял это, пытаясь применить идиомы C ++, Delphi и Java на этих языках. Это приводит к плохим API и плохому коду.

Существуют также конкурирующие школы мысли в разработке API. И, к сожалению, в действительности никто не прав на 100%. По факту, Вы становитесь отличным дизайнером API, когда знаете несколько школ мысли и знаете, когда применить определенную школу мысли к конкретной проблеме.

Функционально LINQ - это не что иное, как синтаксическое упрощение выражения монад. Linq to Objects (понимание списков - даже это уже было бы чрезвычайно полезно), о котором вы говорили, является лишь одним из возможных приложений этого (аналогично List-Monad в Haskell).

Начало построения вашего API на конкретных сценариях использования ; Сделайте свой дизайн конкретным, а не общим. Затем сделайте обобщение позже , если вы обнаружите, что API можно использовать повторно.

В прошлом я видел, как API-интерфейсы реорганизовывались до такой степени, что они стали настолько универсальными, что одним из параметров метода является объект «Параметры» или, что еще хуже, дерево DOM, соответствующее произвольной части XML; например,

void processData(Parameters reportParams);

С этим универсальным подходом:

• Ошибки с меньшей вероятностью будут обнаружены во время компиляции или при просмотре кода и будут обнаруживаться во время выполнения, что затрудняет их отслеживание.
• Код будет меньше читабельный и менее самодокументированный, что затрудняет использование или реализацию.
• Реализация API станет некрасивой, поскольку внутренне необходимо разложить эти «Параметры» объект в конкретный вариант использования и действовать в соответствии с ним.