Bir API sadece kod bakarak ne yaptığını her zaman bilmek gerekir?

Son zamanlarda kendi API'mı geliştiriyorum ve API tasarımına bu kadar ilgi duyduğumda, API tasarımımı nasıl geliştirebileceğimi çok merak ettim.

Birkaç kez ortaya çıkan bir yönü (API'mın kullanıcıları tarafından değil, konu hakkındaki gözlemli tartışmamda): API'yı ne yaptığını çağıran koda bakarak bilmelisiniz .

Örneğin , söylem repo için GitHub'daki bu tartışmaya bakın , şuna benzer:

foo.update_pinned(true, true);

Sadece koda bakarak (parametre adlarını, dokümantasyonu vb. Bilmeden) ne yapacağını tahmin edemez - 2. argüman ne demektir? Önerilen iyileştirme şuna benzer:

foo.pin()
foo.unpin()
foo.pin_globally()

Ve bu bir şeyleri temizler (2. arg, küresel olarak foo'nun sabitlenip sabitlenmeyeceği idi, sanırım) ve bu durumda daha sonra kesinlikle bir gelişme olacağına katılıyorum.

Ancak, sadece koda bakarak ne yaptığını bilmeseniz bile , farklı ancak mantıksal olarak ilgili durumu ayarlamak için yöntemlerin ayrı olanlardan ziyade bir yöntem çağrısı olarak daha iyi açığa çıkabileceği durumlar olabileceğine inanıyorum . (Bu yüzden parametre adlarına ve belgelerine bakmak için başvurmanız gerekir - bir API'ya aşina olmadığım zaman ne kişisel olarak her zaman yapacağım).

Örneğin SetVisibility(bool, string, bool)bir FalconPeer üzerinde bir yöntem maruz ve sadece hatta bakarak kabul:

falconPeer.SetVisibility(true, "aerw3", true);

Ne yaptığı hakkında hiçbir fikriniz olmaz. falconPeerMantıksal anlamda "görünürlüğünü" kontrol eden 3 farklı değer ayarlıyor : birleştirme isteklerini kabul et, sadece şifre ile ve keşif isteklerine cevap ver. Bunu 3 yöntem çağrısına bölmek, API'nın bir kullanıcısına "görünürlük" ün bir yönünü ayarlamaya ve diğerlerini "görünürlük" ün tüm yönlerini ayarlamak için tek bir yöntemi açığa çıkararak onları düşünmeye zorladığımı ayarlamayı unutmasına neden olabilir . Ayrıca, kullanıcı bir yönü değiştirmek istediğinde neredeyse her zaman başka bir yönü değiştirmek isteyecektir ve şimdi bunu tek bir çağrıda yapabilir.

Bunu üç yöntem çağrısına bölmeme arzunuz tamamen anlaşılabilir, ancak boolean parametrelerinin yanı sıra başka seçenekleriniz de var.

Numaralandırma kullanabilirsiniz:

falconPeer.SetVisibility(JoinRequestOptions.Accept, "aerw3", DiscoveryRequestOptions.Reply);

Veya bayraklar numaralandırılır (eğer diliniz destekliyorsa):

falconPeer.SetVisibility(VisibilityOptions.AcceptJoinRequests | VisibilityOptions.ReplyToDiscoveryRequests, "aerw3");

Veya bir Parametre Nesnesi kullanabilirsiniz :

var options = new VisibilityOptions();
options.AcceptJoinRequests = true;
options.ReplyToDiscoveryRequest = true;
options.Password="aerw3";
falconPeer.SetVisibility(options);

Parametre Nesnesi deseni size yardımcı bulabileceğiniz başka avantajlar sağlar. Bir dizi parametrenin etrafından geçilmesini ve serileştirilmesini kolaylaştırır ve belirtilmemiş parametrelere kolayca "varsayılan" değerler verebilirsiniz.

Veya sadece boole parametrelerini kullanabilirsiniz. Microsoft her zaman .NET Framework API ile yapıyor gibi görünüyor, bu yüzden sadece omuz silkebilir ve "onlar için yeterince iyi ise, benim için yeterince iyi" diyebilirsiniz.

Açıkçası, kuralın her zaman istisnaları vardır, ancak kendiniz iyi açıkladığınız gibi, okunabilir bir API'ye sahip olmanın bazı avantajları vardır. Boole argümanları özellikle rahatsız edicidir, çünkü 1) bir niyet ortaya koymazlar ve 2) aslında iki olmanız gereken bir işlevi çağırdığınızı ima ederler, çünkü boole bayrağına bağlı olarak farklı şeyler olacak.

Temel soru şudur: API'nizi daha okunabilir hale getirmek için ne kadar çaba harcamak istiyorsunuz? Dışa doğru ne kadar dışa dönük olursa, daha fazla çaba kolaylıkla haklı görülebilir. Yalnızca başka bir birim tarafından kullanılan bir API ise, o kadar büyük bir anlaşma değildir. Tüm dünyanın kaybetmesine izin vermeyi planladığınız bir REST API'sinden bahsediyorsanız, onu daha anlaşılır hale getirmek için biraz daha çaba harcayabilirsiniz.

Örneğinize gelince, basit bir çözüm var: Görünüşe göre, sizin durumunuzda görünürlük sadece doğru veya yanlış bir şey değil. Bunun yerine, "görünürlük" olarak düşündüğünüz bir dizi şey var. Bir çözüm, Visibilitytüm bu farklı görünürlük türlerini kapsayan bir sınıf gibi bir şey tanıtmak olabilir . Bunları oluşturmak için Oluşturucu desenini daha da uygularsanız, aşağıdaki gibi bir kodla karşılaşabilirsiniz:

Visibility visibility = Visibility.builder()
  .acceptJoinRequests()
  .withPassword("aerw3")
  .replyToDiscoveryRequests()
  .build();
falconPeer.setVisibility(visibility);