web-dev-qa-db-ja.com

誤った名前の概念に固執するか、ラッパーコードでそれらの名前を変更しますか？

基盤となるAPIのラッパーコードを含むライブラリを作成しています。その基礎となるAPIには、「foo」と「bar」という2つの概念があります。英語の辞書での文字どおりの意味は、APIでのそれらの意味の切り替えに近いものです。つまり、「bar」に近いものには「foo」を使用し、逆も同様です。

（好奇心のため：それは基本的にCUDAの「スレッドインデックス」対「スレッドID」です。どちらが3次元であり、どちらが他の線形化であると思いますか？）

今、私のラッパーコードで、私は...

  • 彼らの不正確で紛らわしい用語を使い続けますか？
  • それを元に戻し、私がそうしているときにコメントで大量に説明しますか？
  • 他の用語を使用すると、混乱を招くことはありませんが、より多くの「概念の混乱」が生じますか？

私はあなたが私の特定のケースでのあなたの経験に基づいて入力を求めているのではなく、むしろあなたが直面したかもしれない同様の状況で入力を求めています。また、推奨事項と予期しない考慮事項の両方が役立つでしょう。

注：ラッパーコードは、基になるAPIのallをラップしないため、私のコードのみを実行します。したがって、ユーザーが他のコンテキストで誤った名前の用語に遭遇する可能性はかなりあります。一方、私のラッパーの使用は常に名前空間、つまりquux :: fooまたはquux :: barを介して行われます。

api-designterminologywrapperlesser-evil
5
einpoklum

面白い話：数年前、私はさまざまな関連データ製品を作成している会社で働いていました。多くの製品は密接に関連していました。本質的に同じ製品であるが、形式が異なる場合があります。

ある時点で製品を生成する責任があったときに、製品マネージャーがさまざまな関連製品の最新情報を入手する月1回の大規模なステータスミーティングに出席し始めなければなりませんでした。

最初は自分の特定の領域しか知らなかったので、私はかなり馬鹿げた感じでした、そして、議論には多くの頭字語と製品の略語が散りばめられていました。さらに悪いことに、話している人に応じて、同じ名前が異なるものに使用されることもあれば、同じものに異なる名前が使用されることもあります。

しかし、徐々にそれを拾い上げ、数か月後に私はこれらのミーティングの1つで、製品の所有者と開発者がやり取りしているときに、突然、それらが別の製品について話している！彼らは同じことについて話していると思ったが、そうではなかった！製品は密接に関連しているため、会話は完全な意味をなさないものではありませんでしたが、用語が非常に混乱しているため、他の誰もそれを理解していませんでした。

これについて考える別の方法：あなたがラッパーを使用している誰かであると想像してください。そしておそらくいくつかのAPIドキュメントを見てください。それが私であるかどうかはわかりますが、ドキュメントに2つの項目の定義が逆になっていることに気付きました。それが意図的なものであるとは思わず、ドキュメントの間違いだと思います。おそらく時間を浪費します。何が起こっているのかを理解しようとしています。

結論：用語を逆にしないでください。あなたは将来の混乱を保証するでしょう。 他の開発者が新しい用語が必要であることに同意し、いくつかの完全に新しい名前を考え出し、API名との関係を文書化します。

6
DaveG

あなたがあなたのサービスを使用する必要がある一回に話し、彼らが望むことを何でもできるかどうか確かめてみてください。自分で何かを強制的に変更しないでください。

本の大きさ（高さ/幅/奥行き）についても同じ概念があります。倉庫は本が横になっていると想定し、営業担当者は本が本棚に立っていると想定します。

1
Thomas Koelle

どういうわけかこの問題に遭遇しました。何回もばかげているような気がします。

私のアプローチは、さまざまなロジックを名前がまだ正しい場所にマッピングすることですが、奇妙なことが起こっていることを明確にします。

私が使用する外部APIが次のとおりであると仮定します。

class FooBar 
{
  string foo;
  string bar;
}

そして、私はそれらをパブリックレイヤーから呼び出す必要があります、私は言うようにそれらを定義するかもしれませんこれはビジネス表現です

string businessFoo;
string businessBar;

そして、それらをマッピングするメカニズムを使用します（たとえばAutoMapper）。

var objectToSave = Map(businessFooBar, fooBar); // return FooBar and sets Bar from businessFoo,
// and Foo from businessBar
callingApi.Save(objectToSave);

これにより、私の関心領域が分離され、ビジネスレイヤーがビジネス言語を処理でき、用語を正気で明確に保つことができると感じています。

また、ユニットテストでは、マップが逆方向でないことを確認できます。

var result = Map(businessFoobar, FooBar);
Assert.Equal(businessFoobar.Foo, FooBar.Bar);

それは完璧ではないかもしれませんが、それ以上の混乱を避けることができます。

1
AthomSfere

それらが意味をなすように、用語を確実に切り替えてください。 Façade を既に構築している場合は、 Anti-Corruption Layer にすることもできます。

0
Kilian Foth