Два аргумента, чтобы решить все это

TL;DR;

Используя согласованный двоичный API, его потребителям нужно ввести только один параметр (другой зарезервирован для разработчиков).

Это упрощает использование кода, поскольку подпись функции не изменится; и разрабатывать, потому что код становится более важным, чем инструменты.

Подсчет аргументов

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

Подсчет аргументов также важен, действительно настолько важен, что существует свойство под названием arity, которое означает количество аргументов, которые принимает функция.

Математики и функциональные программисты классифицируют функции, используя одну и ту же нотацию n-арного; в зависимости от автора, получает разные имена, например, 2-арный может называться диладическим или бинарным.

И мой аргумент (ха!) Заключается в том, что, по крайней мере, в javascript можно создать согласованный API, полностью основанный на бинарных функциях.

Единый двоичный API

Подводя итог, я предлагаю, чтобы все ваши открытые функции были в лучшем случае двоичными.

Почему?

Это факт, что IDE и jsdocs эволюционировали, чтобы упростить нашу жизнь, когда дело доходит до «предварительного просмотра», как мы должны вызывать функцию во время разработки: сколько параметров, как они должны быть отсортированы и какие типы должны быть .

Но это также факт, что мы не можем ожидать, что все остальные будут использовать IDE, плагины, расширения или что-либо подобное, что позволяет им предварительно просматривать список аргументов функции.

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

Я мог бы потратить некоторое время, чтобы исправить это, но вместо этого я предпочитаю попросить вас всех изменить способ написания своих API 😂.

(Шучу, однажды я починил его, снова сломал какую-то пробку, и сказал себе, что заставлю его работать, когда я буду менее занят. Я никогда не буду).

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

Как?

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

  1. Первый аргумент - это объект JSON, который заменяет список аргументов функции.
  2. Последний аргумент зарезервирован для тех, кто разрабатывает API (внедрение зависимостей).

Потребители будут заботиться только о передаче первого параметра или вообще ничего не передавать.

Они либо потребляют их как 0-арные (ниладические или нулевые), либо как 1-арные (монадические или унитарные).

Лично я пишу 0-арные функции только в том случае, если пишу геттеры с использованием зарезервированного слова get, которое по дизайну языка не может принимать никаких аргументов.

Оба параметра не используются по умолчанию ни для одного объекта.

Они также не используются напрямую: вы используете их для переопределения возможных значений по умолчанию (которые вам не нужно указывать, если вы не хотите). Эта фаза «нормализации» должна быть первым делом.

Когда?

«Все время», - сказал я, чтобы сделать это по-настоящему последовательным.

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

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

«Правильный и рекомендуемый способ» - это лучше нарушить функцию, поэтому в объекте, содержащем список аргументов, нет необходимости.

Но у каждого проекта есть свои сроки, масштабы и цели по качеству, которые вам нужно будет рассмотреть самостоятельно (или со своей командой).

Где?

Этот метод зарезервирован для API, это означает, что он применяется только к методам, которые вы предоставляете.

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

Заключение

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

Основное преимущество заключается в том, что разработчики могут быстро понять и использовать ваш API. Они могут даже взглянуть на первый объект, чтобы предсказать, как все должно быть !; полагаясь на код, а не на инструменты.

Надеюсь, вам понравилось.

  • Если да, пожалуйста, похлопайте и поделитесь, чтобы помочь другим разработчикам узнать об этом.
  • Если нет, пожалуйста, помогите мне улучшить мысли о коде, (конструктивно) критикуя ниже.

Спасибо!