Çakışan işlev parametrelerini işlemek için bir kalıp var mı?

Verilen başlangıç ​​ve bitiş tarihlerine göre toplam tutarı aylık tutarlara ayıran bir API fonksiyonuna sahibiz.

// 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,
  };
}

Son zamanlarda, bu API için bir tüketici tarih aralığını başka yollarla belirtmek istedi: 1) bitiş tarihi yerine ay sayısını vererek veya 2) aylık ödemeyi sağlayarak ve bitiş tarihini hesaplayarak. Buna cevaben, API ekibi işlevi şu şekilde değiştirdi:

// 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),
  };
}

Bu değişikliğin API'yi karmaşıklaştırdığını hissediyorum. Şimdi Arayan parametreleri (öncelik sırasına göre, yani tarih aralığını hesaplamak için kullanılan içinde tercihini aldığı belirlenmesinde işlevin uygulanması ile gizli sezgisel hakkında endişe gerekiyor monthlyPayment, numMonths, endDate). Arayan, işlev imzasına dikkat etmezse, isteğe bağlı parametrelerin çoğunu gönderebilir ve neden endDategöz ardı edildiğine ilişkin olarak kafaları karışabilir . Bu davranışı işlev belgelerinde belirtiyoruz.

Ayrıca kendisinin kötü bir emsal teşkil ettiğini ve API'ya kendisiyle ilgilenmemesi gereken sorumluluklar eklediğini hissediyorum (yani SRP'yi ihlal ediyor). Varsayalım ek tüketiciler fonksiyonu böyle hesaplanması gibi daha kullanım durumlarını, desteklemek istiyorsanız totalden numMonthsve monthlyPaymentparametreler. Bu işlev zamanla daha karmaşık hale gelecektir.

Tercihim, işlevi olduğu gibi tutmak ve bunun yerine arayanın endDatekendilerini hesaplamasını gerektiriyor . Ancak yanılıyor olabilirim ve yaptıkları değişikliklerin bir API işlevi tasarlamanın kabul edilebilir bir yolu olup olmadığını merak ediyorum.

Alternatif olarak, böyle senaryoları ele almak için ortak bir örnek var mı? API’mizde orijinal işlevi saran daha yüksek dereceli işlevler sağlayabiliriz, ancak bu API'yi engeller. Belki de, işlevin içinde hangi yaklaşımı kullanacağını belirten ek bir flag parametresi ekleyebiliriz.

Uygulamayı görünce, bana burada gerçekten ihtiyacınız olan şey, biri yerine 3 farklı fonksiyon:

Orijinal olanı:

function getPaymentBreakdown(total, startDate, endDate) 

Bitiş tarihi yerine ay sayısını sağlayan kişi:

function getPaymentBreakdownByNoOfMonths(total, startDate, noOfMonths) 

ve aylık ödemeyi sağlayan ve bitiş tarihini hesaplayan:

function getPaymentBreakdownByMonthlyPayment(total, startDate, monthlyPayment) 

Şimdi, artık isteğe bağlı parametreler yoktur ve hangi işlevin nasıl ve hangi amaç için adlandırıldığı oldukça açık olmalıdır. Yorumlarda da belirtildiği gibi, kesinlikle yazılmış bir dilde, biri amaçlarına uymamak kaydıyla 3 farklı işlevi, adlarıyla değil, imzalarıyla ayırt ederek, fonksiyon aşırı yüklemesi de kullanılabilir.

Farklı işlevlerin herhangi bir mantığı çoğaltmanız gerektiği anlamına gelmediğine dikkat edin - dahili olarak, bu işlevler ortak bir algoritmayı paylaşırsa, "özel" bir işleve yeniden yansıtılmalıdır.

Bu gibi senaryoları işlemek için ortak bir desen var mı

İyi API tasarımını tanımlayan bir “kalıp” (GoF tasarım kalıpları anlamında) olduğunu sanmıyorum. Kendini tarif eden isimler kullanarak, daha az parametreli fonksiyonlar, dik (= bağımsız) parametreli fonksiyonlar, okunabilir, bakım yapılabilir ve geliştirilebilir kod yaratmanın temel ilkeleridir. Programlamadaki her iyi fikir mutlaka bir "tasarım deseni" değildir.

Ayrıca kendisinin kötü bir emsal teşkil ettiğini ve API'ya kendisiyle ilgilenmemesi gereken sorumluluklar eklediğini hissediyorum (yani SRP'yi ihlal ediyor). Varsayalım ek tüketiciler fonksiyonu böyle hesaplanması gibi daha kullanım durumlarını, desteklemek istiyorsanız totalden numMonthsve monthlyPaymentparametreler. Bu işlev zamanla daha karmaşık hale gelecektir.

Tamamen haklısın.

Tercihim, işlevi olduğu gibi tutmak ve yerine arayanın bitiş tarihini hesaplamasını gerektiriyor. Ancak yanılıyor olabilirim ve yaptıkları değişikliklerin bir API işlevi tasarlamanın kabul edilebilir bir yolu olup olmadığını merak ediyordum.

Bu da ideal değil, çünkü arayan kodu ilgisiz kazan plakasıyla kirlenecek.

Alternatif olarak, böyle senaryoları ele almak için ortak bir örnek var mı?

Gibi yeni bir tür tanıtın DateInterval. Yapıcıların ne anlama geldiğini ekleyin (başlangıç ​​tarihi + bitiş tarihi, başlangıç ​​tarihi + num ay, ne olursa olsun). Bunu, sisteminizdeki tarih / saat aralıklarını ifade etmek için kullanılan ortak para birimi türleri olarak kabul edin.

Bazen akıcı ifadeler bu konuda yardımcı olur:

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();

Tasarım için yeterli zaman verildiğinde, etki alanına özgü bir dile benzeyen sağlam bir API ile karşılaşabilirsiniz.

Diğer büyük avantaj, otomatik tamamlama özelliğine sahip IDE'lerin kendi kendini keşfedilebilen yeteneklerinden dolayı sezgisel olduğu gibi API belgelerini okumak için neredeyse hiç tereddüt etmemesidir.

Bu konuda https://nikas.praninskas.com/javascript/2015/04/26/fluent-javascript/ veya https://github.com/nikaspran/fluent.js gibi kaynaklar var .

Örnek (ilk kaynak bağlantısından alınmıştır):

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]

Diğer dillerde, adlandırılmış parametreler kullanırsınız . Bu Javscript'te öykünebilir:

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

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

Alternatif olarak, ay sayısını belirleme sorumluluğunu da kırabilir ve onu işlevinizden çıkarabilirsiniz:

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

Ve getpaymentBreakdown, ayın temel sayısını sağlayacak bir nesne alacaktı

Bunlar, örneğin bir işlev döndüren daha yüksek dereceli işlev olacaktır.

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)
  };
}

Ve eğer ayrımcı sendikalar / cebirsel veri türlerine sahip bir sistemle çalışıyor olsaydınız, a TimePeriodSpecification.

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

ve sonra gerçekte birini ve benzeri şeyleri yerine getirmede başarısız olabileceğiniz hiçbir problem yaşanmaz.