Apakah ada pola untuk menangani parameter fungsi yang saling bertentangan?

Kami memiliki fungsi API yang memecah jumlah total menjadi jumlah bulanan berdasarkan tanggal mulai dan berakhir yang diberikan.

// JavaScript

function convertToMonths(timePeriod) {
  // ... returns the given time period converted to months
}

function getPaymentBreakdown(total, startDate, endDate) {
  const numMonths = convertToMonths(endDate - startDate);

  return {
    numMonths,
    monthlyPayment: total / numMonths,
  };
}

Baru-baru ini, konsumen untuk API ini ingin menentukan rentang tanggal dengan cara lain: 1) dengan memberikan jumlah bulan alih-alih tanggal akhir, atau 2) dengan memberikan pembayaran bulanan dan menghitung tanggal akhir. Menanggapi hal ini, tim API mengubah fungsi menjadi sebagai berikut:

// JavaScript

function addMonths(date, numMonths) {
  // ... returns a new date numMonths after date
}

function getPaymentBreakdown(
  total,
  startDate,
  endDate /* optional */,
  numMonths /* optional */,
  monthlyPayment /* optional */,
) {
  let innerNumMonths;

  if (monthlyPayment) {
    innerNumMonths = total / monthlyPayment;
  } else if (numMonths) {
    innerNumMonths = numMonths;
  } else {
    innerNumMonths = convertToMonths(endDate - startDate);
  }

  return {
    numMonths: innerNumMonths,
    monthlyPayment: total / innerNumMonths,
    endDate: addMonths(startDate, innerNumMonths),
  };
}

Saya merasa perubahan ini menyulitkan API. Sekarang penelepon perlu khawatir tentang heuristik yang tersembunyi dengan pelaksanaan fungsi dalam menentukan parameter mengambil preferensi dalam yang digunakan untuk menghitung rentang tanggal (yaitu dengan urutan prioritas monthlyPayment, numMonths, endDate). Jika seorang penelepon tidak memperhatikan tanda tangan fungsi, mereka mungkin mengirim beberapa parameter opsional dan bingung mengapa endDatediabaikan. Kami menentukan perilaku ini dalam dokumentasi fungsi.

Selain itu saya merasa itu menetapkan preseden buruk dan menambahkan tanggung jawab ke API yang seharusnya tidak menjadi perhatiannya (yaitu melanggar SRP). Misalkan konsumen menginginkan fungsi untuk mendukung lebih banyak kasus penggunaan, seperti menghitung totaldari numMonthsdan monthlyPaymentparameter. Fungsi ini akan menjadi semakin rumit dari waktu ke waktu.

Preferensi saya adalah untuk menjaga fungsinya seperti semula dan sebaliknya meminta penelepon untuk menghitung endDatesendiri. Namun, saya mungkin salah dan bertanya-tanya apakah perubahan yang mereka lakukan merupakan cara yang dapat diterima untuk merancang fungsi API.

Atau, apakah ada pola umum untuk menangani skenario seperti ini? Kami dapat menyediakan fungsi tingkat tinggi tambahan di API kami yang membungkus fungsi asli, tetapi ini membengkak API. Mungkin kita bisa menambahkan parameter flag tambahan yang menentukan pendekatan mana yang akan digunakan di dalam fungsi.

Melihat implementasinya, menurut saya apa yang sebenarnya Anda perlukan di sini adalah 3 fungsi berbeda, bukan satu:

Yang asli:

function getPaymentBreakdown(total, startDate, endDate) 

Yang memberikan jumlah bulan, bukan tanggal akhir:

function getPaymentBreakdownByNoOfMonths(total, startDate, noOfMonths) 

dan yang memberikan pembayaran bulanan dan menghitung tanggal akhir:

function getPaymentBreakdownByMonthlyPayment(total, startDate, monthlyPayment) 

Sekarang, tidak ada parameter opsional lagi, dan itu harus cukup jelas fungsi mana yang disebut bagaimana dan untuk tujuan apa. Seperti yang disebutkan dalam komentar, dalam bahasa yang diketik dengan ketat, orang juga dapat menggunakan fungsi yang berlebihan, membedakan 3 fungsi yang berbeda tidak harus dengan nama mereka, tetapi dengan tanda tangan mereka, jika hal ini tidak mengaburkan tujuan mereka.

Perhatikan fungsi-fungsi yang berbeda tidak berarti Anda harus menduplikasi logika apa pun - secara internal, jika fungsi-fungsi ini memiliki algoritma yang sama, itu harus di refactored ke fungsi "pribadi".

apakah ada pola umum untuk menangani skenario seperti ini

Saya tidak berpikir ada "pola" (dalam arti pola desain GoF) yang menggambarkan desain API yang baik. Menggunakan nama yang menggambarkan diri sendiri, fungsi dengan parameter lebih sedikit, fungsi dengan parameter ortogonal (= independen), hanyalah prinsip dasar untuk membuat kode yang dapat dibaca, dipelihara, dan dikembangkan. Tidak setiap ide bagus dalam pemrograman selalu merupakan "pola desain".

Selain itu saya merasa itu menetapkan preseden buruk dan menambahkan tanggung jawab ke API yang seharusnya tidak menjadi perhatiannya (yaitu melanggar SRP). Misalkan konsumen menginginkan fungsi untuk mendukung lebih banyak kasus penggunaan, seperti menghitung totaldari numMonthsdan monthlyPaymentparameter. Fungsi ini akan menjadi semakin rumit dari waktu ke waktu.

Anda benar sekali.

Preferensi saya adalah untuk mempertahankan fungsinya seperti semula dan sebaliknya meminta penelepon untuk menghitung sendiri tanggal akhir. Namun, saya mungkin salah dan bertanya-tanya apakah perubahan yang mereka lakukan merupakan cara yang dapat diterima untuk merancang fungsi API.

Ini juga tidak ideal, karena kode pemanggil akan tercemar dengan pelat ketel yang tidak terkait.

Atau, apakah ada pola umum untuk menangani skenario seperti ini?

Memperkenalkan tipe baru, seperti DateInterval. Tambahkan konstruktor apa pun yang masuk akal (tanggal mulai + tanggal akhir, tanggal mulai + num bulan, apa pun.). Adopsi ini sebagai jenis mata uang umum untuk mengekspresikan interval tanggal / waktu di seluruh sistem Anda.

Terkadang ekspresi lancar membantu dalam hal ini:

let payment1 = forTotalAmount(1234)
                  .breakIntoPayments()
                  .byPeriod(months(2));

let payment2 = forTotalAmount(1234)
                  .breakIntoPayments()
                  .byDateRange(saleStart, saleEnd);

let monthsDue = forTotalAmount(1234)
                  .calculatePeriod()
                  .withPaymentsOf(12.34)
                  .monthly();

Diberi cukup waktu untuk mendesain, Anda dapat membuat API solid yang bertindak serupa dengan bahasa khusus domain.

Keuntungan besar lainnya adalah bahwa IDE dengan autocomplete membuat hampir tidak menarik untuk membaca dokumentasi API, seperti intuitif karena kemampuannya yang dapat ditemukan sendiri.

Ada sumber daya di luar sana seperti https://nikas.praninskas.com/javascript/2015/04/26/fluent-javascript/ atau https://github.com/nikaspran/fluent.js tentang topik ini.

Contoh (diambil dari tautan sumber daya pertama):

let insert = (value) => ({into: (array) => ({after: (afterValue) => {
  array.splice(array.indexOf(afterValue) + 1, 0, value);
  return array;
}})});

insert(2).into([1, 3]).after(1); //[1, 2, 3]

Nah, dalam bahasa lain, Anda akan menggunakan parameter bernama . Ini dapat ditiru dalam Javscript:

function getPaymentBreakdown(total, startDate, durationSpec) { ... }

getPaymentBreakdown(100, today, {endDate: whatever});
getPaymentBreakdown(100, today, {noOfMonths: 4});
getPaymentBreakdown(100, today, {monthlyPayment: 20});

Sebagai alternatif, Anda juga dapat memutuskan tanggung jawab menentukan jumlah bulan dan meninggalkannya di luar fungsi Anda:

getPaymentBreakdown(420, numberOfMonths(3))
getPaymentBreakdown(420, dateRage(a, b))
getPaymentBreakdown(420, paymentAmount(350))

Dan getpaymentBreakdown akan menerima objek yang akan memberikan jumlah bulan dasar

Mereka akan urutan fungsi yang lebih tinggi mengembalikan misalnya fungsi.

function numberOfMonths(months) {
  return {months: (total) => months};
}

function dateRange(startDate, endDate) {
  return {months: (total) => convertToMonths(endDate - startDate)}
}

function monthlyPayment(amount) {
  return {months: (total) => total / amount}
}


function getPaymentBreakdown(total, {months}) {
  const numMonths= months(total);
  return {
    numMonths, 
    monthlyPayment: total / numMonths,
    endDate: addMonths(startDate, numMonths)
  };
}

Dan jika Anda bekerja dengan sistem dengan tipe data serikat / aljabar yang dibedakan, Anda dapat meneruskannya sebagai, katakanlah, a TimePeriodSpecification.

type TimePeriodSpecification =
    | DateRange of startDate : DateTime * endDate : DateTime
    | MonthCount of startDate : DateTime * monthCount : int
    | MonthlyPayment of startDate : DateTime * monthlyAmount : float

dan kemudian tidak ada masalah akan terjadi di mana Anda bisa gagal untuk benar-benar mengimplementasikannya dan seterusnya.