n層アプリケーションのメソッドレベルのドキュメント

Question

私の状況：

私のアプリケーションのデータリクエストチェーンは次のようになります。

(Client) -> (WebService) -> (SQL or OLAP Cube)

クライアントは、生成されたプロキシを使用してWCF Webサービスと通信するSilverlightアプリケーションです。次に、DALコンポーネントを使用して承認を行い、SQL DBおよびOLAPキューブにアクセスします。基本的には、要求を転送するだけです。したがって、各メソッドは4つの異なる場所に存在します。

// WCF Webservice interface and implementation (used by client)
public interface ICatalogService 
public class CatalogService : ICatalogService

// DAL interface and implementation (used by webservice)
public interface ICatalogDataAccessLayer
public class CatalogDataAccessLayer : ICatalogDataAccessLayer    

ここで私の質問、これらの方法を明確に指定するためのドキュメントをどこに置くべきですかクラスまたはインターフェースレベルで、DALまたはWebサービスで？

これまでの私の考え：

消費されるのはコントラクトであるため、インターフェイスでメソッドの仕様を記述するのが最も理にかなっていると思います。ただし、特定の状況ではWebサービスとDALの間に利点はありません。

• 私が唯一の開発者です。ドキュメントを必要とする個別のwebservice-guyまたはclient-guyはありません
• これは閉じたアーキテクチャであり、ウェブサービスは公開されていません
• 将来、このプロジェクトに取り組んでいるすべての人が、このプロジェクトのすべてのコンポーネントにアクセスできるようになります（ドキュメントはどこにいても見つかります）

それで、あなたはそれについてどう思いますか？この場合、メソッドレベルのドキュメントはどこに置くべきですか？

Answer 1

ほとんどの人は、WebサービスがDALよりも多く文書化されることを期待すると思います（特にDALがほとんど生成されたコードである場合：これらはパススルーメソッドであると推測します）。将来的にそれを扱う人のために、DALのコメントにWebサービスのドキュメントへのポインターを追加します。

理由は2つあります。まず、Webサービスは実際の対話ポイントです（したがって、さらにクライアントを追加できるポイントです。つまり、サービスを文書化することはプラスになります）。 2番目は、DALが「付加価値」を提供するように聞こえないことですWebサービスを介して（説明されている構成で）、相互作用と価値の実際のポイントを指すのが理にかなっています。

Webサービスレイヤーなしで別のクライアントによる再利用でDALが脅かされた場合...明らかに、それは逆方向に傾く（または重複したコメントを自動化する）ために物事を変更します。