Swift APIデザインガイドラインに準拠したメソッドとパラメータの名前付け

Question

現在のAPIデザインガイドラインを読んでもわかりません。次のバージョンのほうが優れています。

class MediaLoader {} 
class MediaRequest {} 

let mediaLoader = MediaLoader() 
let mediaRequest = MediaRequest() 

// Option 1 
mediaLoader.add(request: mediaRequest) 

// Option 2 
mediaLoader.add(mediaRequest: mediaRequest) 

// Option 3 
mediaLoader.addRequest(mediaRequest) 

// Option 4 
mediaLoader.add(mediaRequest) 

上記のどれが現在のAPIデザインガイドラインに最も適していますか？

Answer 1

答えは、MediaLoaderの目的とセマンティクスに大きく依存します。 MediaLoaderがmediaRequestsのコレクションに過ぎない場合、文法的に流れてコンテキスト内で意味があるため、.add（mediaRequest）は移動する方法です。

一方、mediaRequestがその目的に貢献する多くの異なるものの1つに過ぎない場合、.add（）だけでも文を正しく読み取るための十分なコンテキストが伝達されません。たとえば、ディスプレイチャネルやフィルタを追加することもできますが、単に.add（何か）と言うだけでは十分ではありません。これは、関係を説明する拡張名を使用する場合です。例えば。addRequest（）、addChannel（）、addFilter（）。

しかし、.add（request：...）ではなく、最初のパラメータの名前を使用することは、リレーションシップを区別する理想的な方法ではないためです。代わりに、追加が実行される方法や要求へのアクセス方法を明確にするために使用する必要があります。これにより、最も頻繁で直接的なユースケースの「名前のない」変種が残されます。例えば.add（fromTemplate：webRequesTemplate）または.addRequest（fromTemplate：webTemplate）。