n 层应用程序中的方法级文档

Question

我的情况：

我的应用程序的数据请求链如下所示：

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

客户端是一个 Silverlight 应用程序，它使用生成的代理与 WCF Web 服务进行通信。反过来，它使用 DAL 组件进行授权并访问 SQL DB 和 OLAP 多维数据集， 基本上它只是转发请求。因此，每种方法存在于四个不同的地方：

// 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 服务上？

到目前为止我的想法：

我想说，在接口上编写方法规范是最有意义的，因为它是正在使用的合约。然而，在我的具体情况下，我没有看到 webservice 和 DAL 之间的优势：

• 我是唯一的开发人员，没有单独的网络服务人员或客户端人员需要文档
• 这是一个封闭的架构，webservice不公开
• 将来从事该项目的每个人都可以访问它的所有组件（并且可以找到文档，无论它们在哪里）

那么，您对此有何看法？在这种情况下，我应该将方法级文档放在哪里？

Answer 1

我认为大多数人会期望 Web 服务比 DAL 拥有更多的文档（特别是如果 DAL 主要是生成的代码）：我猜是因为这些是传递方法）。我会在 DAL 注释中添加指向 Web 服务文档的指针，供将来使用它的人员使用。

原因是双重的。首先，Web 服务是真正的交互点（因此可以添加更多客户端，这意味着记录服务是一个优点）。第二个是，DAL 听起来确实不像它通过 Web 服务（在所描述的配置中）提供“附加值”，因此回到交互和价值的真实点是有意义的。

如果 DAL 曾受到其他客户端重用的威胁 没有 Web服务层...显然，这会改变事情以相反的方式倾斜（或自动重复评论）。