Как Вы определяете хороший или плохой API? [закрытый]

Question

Как Вы определяете хороший или плохой API? [закрытый]

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

Итак, я просто скопирую соответствующие части этих двух ссылок здесь. Таким образом, мы можем иметь:

Лучшее, что можно сделать для клонирования объектов в c sharp!

Прежде всего, это все наши варианты:

Вручную с ICloneable , который является Shallow , а не Тип-Safe
MemberwiseClone , который использует ICloneable
Reflection , используя Activator.CreateInstance и рекурсивный MemberwiseClone
Сериализация , как указано предпочтительным ответом johnc
Промежуточный язык, о котором я понятия не имел , как работает
Методы расширения, такие как эта пользовательская структура клона Havard Straden
Деревья экспрессии

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

Почему я выбираю ICloneable (т.е. вручную)

Г-н Venkat Subramaniam (избыточная ссылка здесь) подробно объясняет, почему .

Все его статьи кругом вокруг примера, который пытается применяться в большинстве случаев, используя 3 объекта: Person , Мозг и Город . Мы хотим клонировать человека, который будет иметь свой собственный мозг, но тот же город.

Это моя слегка измененная версия его вывода:

Копирование объекта с помощью указание New, за которым следует имя класса, часто приводит к тому, что код не расширяется. Использование клона, применение шаблона прототипа, является лучшим способом достижения этого. Однако использование клона, как это предусмотрено в C # (и Java), может быть довольно проблематичным. Лучше предоставить защищенный (непубличный) конструктор копирования и вызвать его из метода клонирования. Это дает нам возможность делегировать задачу создания объекта на экземпляр самого класса, тем самым обеспечивая расширяемость, а также безопасное создание объектов с использованием защищенного конструктора копии.
blockquote>
Надеюсь, это реализация может сделать все ясно:
public class Person : ICloneable
{
    private final Brain brain; // brain is final since I do not want 
                // any transplant on it once created!
    private int age;
    public Person(Brain aBrain, int theAge)
    {
        brain = aBrain; 
        age = theAge;
    }
    protected Person(Person another)
    {
        Brain refBrain = null;
        try
        {
            refBrain = (Brain) another.brain.clone();
            // You can set the brain in the constructor
        }
        catch(CloneNotSupportedException e) {}
        brain = refBrain;
        age = another.age;
    }
    public String toString()
    {
        return "This is person with " + brain;
        // Not meant to sound rude as it reads!
    }
    public Object clone()
    {
        return new Person(this);
    }
    …
}
Теперь рассмотрим вопрос о том, какой класс следует из Person.
public class SkilledPerson extends Person
{
    private String theSkills;
    public SkilledPerson(Brain aBrain, int theAge, String skills)
    {
        super(aBrain, theAge);
        theSkills = skills;
    }
    protected SkilledPerson(SkilledPerson another)
    {
        super(another);
        theSkills = another.theSkills;
    }

    public Object clone()
    {
        return new SkilledPerson(this);
    }
    public String toString()
    {
        return "SkilledPerson: " + super.toString();
    }
}
Вы можете попробовать запустить следующий код:
public class User
{
    public static void play(Person p)
    {
        Person another = (Person) p.clone();
        System.out.println(p);
        System.out.println(another);
    }
    public static void main(String[] args)
    {
        Person sam = new Person(new Brain(), 1);
        play(sam);
        SkilledPerson bob = new SkilledPerson(new SmarterBrain(), 1, "Writer");
        play(bob);
    }
}
Выведенный результат будет:
This is person with Brain@1fcc69
This is person with Brain@253498
SkilledPerson: This is person with SmarterBrain@1fef6f
SkilledPerson: This is person with SmarterBrain@209f4e
Обратите внимание, что если мы храним счетчик количества объектов, клон, реализованный здесь, будет содержать правильный подсчет количества объектов.

61

api api-design

задан fmsf 5 June 2009 в 23:42

14 ответов

Вы не должны читать документацию для использования его правильно.

знак потрясающего API.

43

ответ дан Quibblesome 24 November 2019 в 16:59

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

существует также вопрос вкуса. API могут соблюсти каждое правило в любом своде правил, и все еще высосать, из-за рабского соблюдения различных идеологий в моде. Недавний преступник является ориентацией шаблона, где Шаблоны "одиночка" (немного больше, чем инициализированные глобальные переменные) и Шаблоны "фабрика" (способ параметризовать конструкцию, но часто реализовываемый если не необходимый) злоупотребляются. В последнее время более вероятно, что Инверсия управления (IoC) и связала взрыв в количестве крошечных интерфейсных типов, которое добавляет избыточную концептуальную сложность к проектам.

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

14

ответ дан Barry Kelly 24 November 2019 в 16:59

Полезный - это обращается к потребностям, которые уже не удовлетворены (или изменяет к лучшему существующие)
Легкий объяснить - основное понимание того, что это делает должно быть просто схватить
, Следует за некоторой объектной моделью некоторой проблемной области или реальный. Это использует конструкции, которые имеют смысл
Корректное использование синхронных и асинхронных вызовов. (не блокируйтесь для вещей, которые занимают время)
, Хорошее поведение по умолчанию - если это возможно, позволяет расширяемость и тонкую настройку, но обеспечивает значения по умолчанию для всего, что необходимо для простых случаев
Демонстрационное использование и рабочие примеры приложения. Это является, вероятно, самым важным из всех.
Превосходная документация
Ест, Ваш собственный корм для собак (если применимо)
Сохраняют его маленьким или сегментируют его так, чтобы это не было одно огромное загрязненное пространство. Сохраните наборы функциональности отличными и изолированными с немногими если любые зависимости.

существуют больше, но это - хорошее начало

12

ответ дан Tim 24 November 2019 в 16:59

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

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

7

ответ дан T.E.D. 24 November 2019 в 16:59

А хороший API имеет семантическую модель близко к вещи, которую это описывает.

, Например, API для создания и управления электронными таблицами Excel имел бы классы как Workbook, Sheet, и Cell, с методами как Cell.SetValue(text) и Workbook.listSheets().

7

ответ дан Dan Vinton 24 November 2019 в 16:59

Плохой API является тем, который не используется его целевой аудиторией.

А хороший API является тем, который используется его целевой аудиторией для цели, для которой это было разработано.

А большой API является тем, который используется и его целевой аудиторией для его намеченной цели, и непреднамеренной аудиторией по причинам, непредвиденным ее разработчиками.

, Если Amazon публикует свой API и как SOAP и как REST и остальных, версия побеждает, который не означает, что базовый API SOAP был плох.

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

3

ответ дан duffymo 24 November 2019 в 16:59

Я думаю, что хороший API должен позволить пользовательский IO и рычаги управления памятью, если это применимо.

А типичный пример - Вы, имеют Ваш пользовательский сжатый формат архива для данных по диску, и сторонняя библиотека с плохим API хочет получить доступ к данным по диску и ожидает путь к файлу, где это может загрузить свои данные.

Эта ссылка имеет некоторые положительные стороны: http://gamearchitect.net/2008/09/19/good-middleware/

1

ответ дан Laserallan 24 November 2019 в 16:59

Если API производит сообщение об ошибке, удостоверьтесь, чтобы сообщение и диагностика выручили работу разработчика, какова проблема.

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

1

ответ дан Alan 24 November 2019 в 16:59

API плох, когда он плохо документируется .

API хорош, когда он хорошо документируется и следует стандарту кодирования .

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

код Комментария, пишущий хорошо объясненный руководство для API Обязательно.

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

я записал немного о кодировании структуры здесь

0

ответ дан Filip Ekberg 24 November 2019 в 16:59

Я думаю, что является главным, удобочитаемость, которой я имею в виду качество, которое делает самое большое число программистов для понимания то, что код делает за самое короткое количество времени. Но оценка, какая часть программного обеспечения читаема и которая не является, имеет то неописуемое человеческое качество: нечеткость. Моменты, которые Вы упоминаете, действительно частично преуспевают в том, чтобы кристаллизовать его. Однако в целом это должно остаться индивидуальным делом, и было бы действительно трудно придумать универсальные правила.

0

ответ дан Frederick The Fool 24 November 2019 в 16:59

Мне всегда нравилась эта статья в названных Вопросах Дизайна API очереди

http://queue.acm.org/detail.cfm?id=1255422

И это столбцы также, который имеет дело с вопросами проектирования API:

http://queue.acm.org/detail.cfm?id=1229903

6

ответ дан jasonco 24 November 2019 в 16:59

Хороший API - это тот, который делает простые вещи простыми (минимум шаблонов и кривой обучения для выполнения наиболее распространенных вещей) и возможными сложные вещи (максимальная гибкость, как можно меньше предположений). Посредственный API - это тот, который хорошо справляется с одной из этих задач (либо безумно простой, но только если вы пытаетесь делать действительно простые вещи, либо безумно мощный, но с действительно крутой кривой обучения и т. Д.). Ужасный API - это тот, который не справляется ни с одним из этих качеств.

2

ответ дан 24 November 2019 в 16:59

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

Статьи

Книги:

2

ответ дан 24 November 2019 в 16:59

Другие вопросы по тегам:

api api-design

Как Вы определяете хороший или плохой API? [закрытый]

Лучшее, что можно сделать для клонирования объектов в c sharp!

Почему я выбираю ICloneable (т.е. вручную)

14 ответов

Похожие вопросы: