Должен ли API принимать правильную последовательность вызовов или проверять предположения?

Question

У меня есть 2 вызова API для реализации, давайте назовем их «ShouldDoSomething» и «DoSomething». Первый - это проверка того, нужно ли предпринимать какое-то конкретное действие, а другой действительно выполняет это действие. Естественно, выполнение действия необходимо или допустимо только в том случае, если тест возвращает значение true. Есть случаи, когда тест необходим без фактического выполнения действия, поэтому необходимы оба.

Должен ли вызов действия внутренне запускать тест и становиться неактивным, если он не нужен, или реализация должна предполагать, что он будет вызываться только в случае, если тест уже вернул true? Кажется, проще и безопаснее проверить допущения, но тогда у вызова 'action' есть 3 возможных состояния возврата вместо двух (успех, сбой и не требуется). Другой подход заключается в том, чтобы сделать тест утверждением и прервать его, если действие было вызвано без необходимости. (это в C, поэтому исключения не очень хорошая идея)

Но все сводится к выбору - более простые вызовы API или меньшее количество вызовов API?

Answer 1

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

Если вы решили использовать первую опцию, вам действительно нужно добавить «не нужное» возвращаемое состояние или оно может просто указывать «успех», если операция не нужна? Не добавляйте сложность, если в этом нет необходимости.

Answer 2

Стивен Кэнон прав относительно последовательности и документации.

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

Answer 3

Я думаю, что было бы лучше пойти с:

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

Так, например, если вызывается DoSomething и «DoDoSomething »говорит вам, что вам не следует предпринимать это конкретное действие,« DoSomething должен прервать работу, ничего не делая.проверка того, следует ли вызывать «DoSomething»?

Я думаю, что это также сводится к тому, что будет изменено. Может ли это быть фатальным, если вызвано ненадлежащим образом?тогда это на самом деле не имеет значения.

Я бы сказал, что безопасный путь - это путь.

Надеюсь, это поможет.

Answer 4

Простейшим API (с точки зрения пользователя) будет иметь функцию DoSomethingIfNeeded(), которая позволит вам позаботиться об условиях.Зачем беспокоить пользователя?

Наименее дружественный пользовательский интерфейс - тот, который говорит: «Теперь вызовите одну из этих функций! Нет, не эту!»